From 32c8966b255b2941142146d0e2628c89621521a0 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Fri, 17 Jul 2026 16:06:22 -0400
Subject: [PATCH 1/4] feat(appkit): auto-start the app under test for agent
 evals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a Playwright-style `webServer` so `appkit agent eval` can boot the app
itself instead of requiring a server to be running.

- Root `evals.config.ts` (project root, via defineEvalConfig) carries run-wide
  settings: `baseUrl` + `webServer { command, url?, timeoutMs?, reuseExisting? }`.
  appkit exposes `loadRootEvalConfig` / `findRootEvalConfig`; the per-agent
  config keeps its narrow maxConcurrency/timeoutMs role.
- CLI resolves baseUrl/concurrency/timeout as flag > root config > default, and
  before running: reuses a server already answering at `url` (default) or spawns
  `command`, polls until any HTTP response or timeout, then SIGTERMs the process
  group in a finally. A reused server is left untouched.
- `--url` default changed 3000 → 8000 (the port these apps actually use).

Verified end-to-end against dev-playground: cold start boots + tears down; warm
start reuses and leaves the dev server running.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 apps/dev-playground/evals.config.ts           |  15 ++
 packages/appkit/src/evals/discover.ts         |  11 ++
 packages/appkit/src/evals/index.ts            |   3 +
 packages/appkit/src/evals/run-evals.ts        |  15 ++
 .../appkit/src/evals/tests/discover.test.ts   |  18 ++-
 packages/appkit/src/evals/types.ts            |  38 ++++-
 .../shared/src/cli/commands/agent/eval.ts     | 131 ++++++++++++++++--
 7 files changed, 221 insertions(+), 10 deletions(-)
 create mode 100644 apps/dev-playground/evals.config.ts

diff --git a/apps/dev-playground/evals.config.ts b/apps/dev-playground/evals.config.ts
new file mode 100644
index 000000000..6ad057c1b
--- /dev/null
+++ b/apps/dev-playground/evals.config.ts
@@ -0,0 +1,15 @@
+import { defineEvalConfig } from "@databricks/appkit/beta";
+
+/**
+ * Root eval config for the dev-playground. `webServer` lets `appkit agent eval`
+ * boot the app on demand (reusing an already-running dev server) instead of
+ * requiring it to be started by hand.
+ */
+export default defineEvalConfig({
+  baseUrl: "http://localhost:8000",
+  webServer: {
+    // Monorepo fixture command; a template project would use `npm run dev`.
+    command: "pnpm --filter=dev-playground dev",
+    timeoutMs: 90_000,
+  },
+});
diff --git a/packages/appkit/src/evals/discover.ts b/packages/appkit/src/evals/discover.ts
index b6c8b6e88..e009ec362 100644
--- a/packages/appkit/src/evals/discover.ts
+++ b/packages/appkit/src/evals/discover.ts
@@ -76,6 +76,17 @@ export function discoverEvalFiles(rootDir: string): DiscoveredEval[] {
   );
 }
 
+/**
+ * Path to the root `evals.config.ts` (from {@link defineEvalConfig}) at
+ * `<rootDir>/evals.config.ts`, or `undefined` when absent. The root config
+ * holds run-wide settings (`baseUrl`, `webServer`); it's distinct from the
+ * per-agent configs found by {@link discoverEvalConfigs}.
+ */
+export function findRootEvalConfig(rootDir: string): string | undefined {
+  const file = path.join(rootDir, "evals.config.ts");
+  return isFile(file) ? file : undefined;
+}
+
 /**
  * Discover the per-agent `evals.config.ts` (from {@link defineEvalConfig}) at
  * `<rootDir>/server/agents/<agent>/evals/evals.config.ts`. Config is per-agent:
diff --git a/packages/appkit/src/evals/index.ts b/packages/appkit/src/evals/index.ts
index afed3046a..9c0e539bf 100644
--- a/packages/appkit/src/evals/index.ts
+++ b/packages/appkit/src/evals/index.ts
@@ -19,6 +19,7 @@ export {
   type DiscoveredEvalConfig,
   discoverEvalConfigs,
   discoverEvalFiles,
+  findRootEvalConfig,
 } from "./discover";
 export { createHttpDriver, type HttpDriverOptions } from "./http-driver";
 export {
@@ -49,6 +50,7 @@ export { type RunEvalOptions, runEval } from "./run-eval";
 export {
   type EvalProgress,
   type EvalRunSummary,
+  loadRootEvalConfig,
   type RunEvalsOptions,
   runEvalsInDir,
   runWithRetries,
@@ -61,6 +63,7 @@ export type {
   EvalDefinition,
   EvalDriver,
   EvalResult,
+  EvalWebServer,
   Matcher,
   MatchResult,
   Severity,
diff --git a/packages/appkit/src/evals/run-evals.ts b/packages/appkit/src/evals/run-evals.ts
index 2ad9e4bcd..68c9b3cf7 100644
--- a/packages/appkit/src/evals/run-evals.ts
+++ b/packages/appkit/src/evals/run-evals.ts
@@ -7,6 +7,7 @@ import {
   type DiscoveredEval,
   discoverEvalConfigs,
   discoverEvalFiles,
+  findRootEvalConfig,
 } from "./discover";
 import { createHttpDriver } from "./http-driver";
 import { configureJudge, teardownJudge } from "./judge";
@@ -136,6 +137,20 @@ async function loadEvalConfig(file: string): Promise<EvalConfig | undefined> {
   return resolveConfigDefault(mod);
 }
 
+/**
+ * Load the root `evals.config.ts` under `rootDir` (the project root), or return
+ * `undefined` when there is none. This is the run-wide config carrying
+ * `baseUrl`/`webServer`; the CLI reads it to resolve options and manage the
+ * app-under-test lifecycle before calling {@link runEvalsInDir}.
+ */
+export async function loadRootEvalConfig(
+  rootDir: string,
+): Promise<EvalConfig | undefined> {
+  const file = findRootEvalConfig(rootDir);
+  if (!file) return undefined;
+  return loadEvalConfig(file);
+}
+
 /**
  * Unwrap the config default export across module-interop shapes (see
  * {@link resolveEvalDefault}). A config has no `.test`, so the first plain
diff --git a/packages/appkit/src/evals/tests/discover.test.ts b/packages/appkit/src/evals/tests/discover.test.ts
index cd2d949af..67afc9cc1 100644
--- a/packages/appkit/src/evals/tests/discover.test.ts
+++ b/packages/appkit/src/evals/tests/discover.test.ts
@@ -4,7 +4,11 @@ import path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 
-import { discoverEvalConfigs, discoverEvalFiles } from "../discover";
+import {
+  discoverEvalConfigs,
+  discoverEvalFiles,
+  findRootEvalConfig,
+} from "../discover";
 
 let root: string;
 
@@ -61,3 +65,15 @@ describe("discoverEvalConfigs", () => {
     expect(discoverEvalConfigs(root)).toEqual([]);
   });
 });
+
+describe("findRootEvalConfig", () => {
+  test("finds a root evals.config.ts", () => {
+    write("evals.config.ts");
+    expect(findRootEvalConfig(root)).toBe(path.join(root, "evals.config.ts"));
+  });
+
+  test("returns undefined when absent (and ignores per-agent configs)", () => {
+    write("config/agents/support/evals/evals.config.ts");
+    expect(findRootEvalConfig(root)).toBeUndefined();
+  });
+});
diff --git a/packages/appkit/src/evals/types.ts b/packages/appkit/src/evals/types.ts
index 463c92533..bd274f5be 100644
--- a/packages/appkit/src/evals/types.ts
+++ b/packages/appkit/src/evals/types.ts
@@ -170,7 +170,39 @@ export interface EvalDefinition {
   test(t: TestContext): Promise<void> | void;
 }
 
-/** Per-directory config from `evals.config.ts` (see {@link defineEvalConfig}). */
+/**
+ * Auto-start config for the app under test, à la Playwright's `webServer`. When
+ * set in a root `evals.config.ts`, the CLI boots the app before running evals
+ * and tears it down after — so you don't have to start the server by hand.
+ */
+export interface EvalWebServer {
+  /** Shell command that starts the app, e.g. `"npm run dev"`. */
+  command: string;
+  /**
+   * URL polled until it answers before evals start. Defaults to the run's
+   * `baseUrl` (`--url`). Readiness = any HTTP response (a 404 still proves the
+   * server is up).
+   */
+  url?: string;
+  /** How long to wait for `url` to answer before giving up. Defaults to 60s. */
+  timeoutMs?: number;
+  /**
+   * When `true` (default), reuse a server already answering at `url` instead of
+   * spawning one — so a running `dev` server is used as-is. Set `false` to
+   * always spawn a fresh server.
+   */
+  reuseExisting?: boolean;
+}
+
+/**
+ * Eval config from `evals.config.ts` (via {@link defineEvalConfig}).
+ *
+ * Two scopes share this shape: a **root** `evals.config.ts` (project root) may
+ * set run-wide settings — `baseUrl` and `webServer` — plus defaults for
+ * `maxConcurrency`/`timeoutMs`; a **per-agent** `server/agents/<id>/evals/evals.config.ts`
+ * sets only that agent's `maxConcurrency`/`timeoutMs` overrides (`baseUrl`/
+ * `webServer` there are ignored — server lifecycle is run-wide).
+ */
 export interface EvalConfig {
   /** LLM judge config. Defaults to the agent's own serving endpoint. */
   judge?: { model?: string };
@@ -178,6 +210,10 @@ export interface EvalConfig {
   maxConcurrency?: number;
   /** Default per-eval timeout. */
   timeoutMs?: number;
+  /** Base URL of the app to drive (root config only). Overridden by `--url`. */
+  baseUrl?: string;
+  /** Auto-start the app under test (root config only). */
+  webServer?: EvalWebServer;
 }
 
 /** The outcome of running one eval. */
diff --git a/packages/shared/src/cli/commands/agent/eval.ts b/packages/shared/src/cli/commands/agent/eval.ts
index 5bda63492..3bf1d30a9 100644
--- a/packages/shared/src/cli/commands/agent/eval.ts
+++ b/packages/shared/src/cli/commands/agent/eval.ts
@@ -1,3 +1,4 @@
+import { type ChildProcess, spawn } from "node:child_process";
 import fs from "node:fs";
 
 import { Command, Option } from "commander";
@@ -55,6 +56,7 @@ interface EvalRunner {
     token?: string;
   }): unknown;
   formatEvalHeadline(result: unknown): string;
+  loadRootEvalConfig(rootDir: string): Promise<EvalConfig | undefined>;
   evalGlyph(result: unknown): string;
   formatEvalDetail(result: unknown): string[];
   formatSummaryLine(results: unknown[]): string;
@@ -63,6 +65,19 @@ interface EvalRunner {
   summarize(results: unknown[]): { allPassed: boolean; passRate: number };
 }
 
+/** Subset of `@databricks/appkit/beta`'s `EvalConfig` the CLI reads. */
+interface EvalConfig {
+  maxConcurrency?: number;
+  timeoutMs?: number;
+  baseUrl?: string;
+  webServer?: {
+    command: string;
+    url?: string;
+    timeoutMs?: number;
+    reuseExisting?: boolean;
+  };
+}
+
 /**
  * Loaded at runtime from the consuming project so this command (which ships in
  * `@databricks/shared`) doesn't take a build-time dependency on appkit. The
@@ -97,8 +112,83 @@ function positiveInt(raw: string | undefined): number | undefined {
   return n > 0 ? n : undefined;
 }
 
+/** True when `url` answers with any HTTP response (a 404 still proves it's up). */
+async function isServerUp(url: string): Promise<boolean> {
+  try {
+    await fetch(url, { signal: AbortSignal.timeout(2000) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start the app under test per a root config's `webServer`, à la Playwright:
+ * reuse a server already answering at `url` (unless `reuseExisting: false`),
+ * else spawn `command`, poll `url` until it answers or `timeoutMs` elapses.
+ * Returns a `stop()` that kills the spawned process group (a no-op when the
+ * server was reused). Logs go to stderr so a machine reporter's stdout stays
+ * clean. Throws if the server never comes up.
+ */
+async function startWebServer(
+  webServer: NonNullable<EvalConfig["webServer"]>,
+  baseUrl: string,
+): Promise<{ stop: () => void }> {
+  const url = webServer.url ?? baseUrl;
+  const reuse = webServer.reuseExisting !== false;
+  const noop = { stop: () => {} };
+
+  if (reuse && (await isServerUp(url))) {
+    console.error(`Reusing server already running at ${url}`);
+    return noop;
+  }
+
+  console.error(`Starting web server: ${webServer.command}`);
+  // `detached` + a negative-PID kill lets us tear down the whole process group
+  // (dev servers spawn child processes). stdout/stderr inherit so the user sees
+  // build output; the server's stdout is not our report stream.
+  const child: ChildProcess = spawn(webServer.command, {
+    shell: true,
+    detached: true,
+    stdio: "inherit",
+  });
+
+  let exited = false;
+  child.on("exit", () => {
+    exited = true;
+  });
+
+  const stop = (): void => {
+    if (exited || child.pid === undefined) return;
+    try {
+      process.kill(-child.pid, "SIGTERM");
+    } catch {
+      // Group already gone, or never became a leader — best-effort.
+    }
+  };
+
+  const deadline = Date.now() + (webServer.timeoutMs ?? 60_000);
+  try {
+    while (Date.now() < deadline) {
+      if (exited) throw new Error("web server exited before becoming ready");
+      if (await isServerUp(url)) {
+        console.error(`Web server ready at ${url}`);
+        return { stop };
+      }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  } catch (err) {
+    stop();
+    throw err;
+  }
+  stop();
+  throw new Error(
+    `web server did not respond at ${url} within ${webServer.timeoutMs ?? 60_000}ms`,
+  );
+}
+
 interface EvalOptions {
-  url: string;
+  url?: string;
   strict?: boolean;
   root?: string;
   header?: string[];
@@ -228,6 +318,15 @@ async function runAgentEval(
 ): Promise<void> {
   const runner = await loadRunner();
 
+  // Root `evals.config.ts` (project root) carries run-wide settings — baseUrl,
+  // webServer, and defaults for concurrency/timeout. A CLI flag always wins.
+  const rootDir = opts.root ?? process.cwd();
+  const config = (await runner.loadRootEvalConfig(rootDir)) ?? {};
+
+  // Base URL: --url flag > config.baseUrl > built-in default. `--url` has no
+  // commander default so an unset flag is undefined and lets config win.
+  const baseUrl = opts.url ?? config.baseUrl ?? "http://localhost:8000";
+
   // Databricks credentials shared by auth resolution and the workspace client:
   // an explicit flag/DATABRICKS_* env wins, else the SDK resolves from the CLI
   // profile.
@@ -247,8 +346,13 @@ async function runAgentEval(
   const warehouseId = opts.warehouseId ?? process.env.DATABRICKS_WAREHOUSE_ID;
   const workspaceClient = runner.resolveWorkspaceClient(credentials);
 
-  // Runner-level default per-eval timeout (ms). A per-eval `timeoutMs` wins.
-  const timeoutMs = positiveInt(opts.timeout);
+  // Max concurrency: the `--concurrency` flag (already parsed by its argParser)
+  // wins over the root config's value; else the runner's built-in default.
+  const concurrency = opts.concurrency ?? config.maxConcurrency;
+
+  // Runner-level default per-eval timeout (ms). --timeout flag wins over the
+  // root config; a per-eval `timeoutMs` overrides both (applied in the runner).
+  const timeoutMs = positiveInt(opts.timeout) ?? config.timeoutMs;
 
   // Extra attempts for evals that fail on an infra error (turn/timeout). Junk
   // or negative input falls back to no retries.
@@ -264,23 +368,29 @@ async function runAgentEval(
     else console.log(msg);
   };
 
+  // Boot the app under test if the root config declares a webServer (reuses an
+  // already-running server unless told otherwise); always torn down after.
+  const server = config.webServer
+    ? await startWebServer(config.webServer, baseUrl)
+    : undefined;
+
   let summary: EvalRunSummary;
   try {
     summary = await runner.runEvalsInDir({
-      rootDir: opts.root,
-      baseUrl: opts.url,
+      rootDir,
+      baseUrl,
       filter,
       tags: opts.tag,
       strict: opts.strict,
       headers: opts.header ? parseHeaders(opts.header) : undefined,
-      concurrency: opts.concurrency,
+      concurrency,
       mlflow: resolveMlflow(opts, auth),
       judge: resolveJudge(opts, auth),
       workspaceClient,
       warehouseId,
       timeoutMs,
       retries,
-      onEvent: makeProgressReporter(runner, opts.url, machine, info),
+      onEvent: makeProgressReporter(runner, baseUrl, machine, info),
     });
   } catch (err) {
     // Setup failures (e.g. a bad --experiment for the MLflow run) reject before
@@ -291,6 +401,8 @@ async function runAgentEval(
     );
     process.exitCode = 1;
     return;
+  } finally {
+    server?.stop();
   }
 
   // The final human summary always shows (stderr for machine reporters so it
@@ -348,7 +460,10 @@ export const agentEvalCommand = new Command("eval")
     "[filter]",
     "Only run evals whose <agent>/<id> contains this substring (or an exact agent id)",
   )
-  .option("--url <url>", "Base URL of the running app", "http://localhost:3000")
+  .option(
+    "--url <url>",
+    "Base URL of the app to drive (default: evals.config.ts baseUrl, else http://localhost:8000)",
+  )
   .option("--strict", "Fail on soft-assertion misses too", false)
   .option(
     "--concurrency <n>",

From 93270c63b756ccba5b2bb24bc3644947042d44d9 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Mon, 20 Jul 2026 12:57:03 +0200
Subject: [PATCH 2/4] docs: regenerate API reference for agent evals

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 .../appkit/Function.discoverEvalConfigs.md    |  20 ++
 .../api/appkit/Function.findRootEvalConfig.md |  20 ++
 .../api/appkit/Function.formatResultsJUnit.md |  20 ++
 .../api/appkit/Function.formatResultsJson.md  |  19 ++
 .../api/appkit/Function.loadRootEvalConfig.md |  20 ++
 .../api/appkit/Function.readEvalDataset.md    |  26 ++
 .../appkit/Function.resolveWorkspaceClient.md |  21 ++
 docs/docs/api/appkit/Function.runBounded.md   |  34 +++
 .../api/appkit/Function.runWithRetries.md     |  22 ++
 docs/docs/api/appkit/Function.userTurns.md    |  26 ++
 .../api/appkit/Interface.AssertionHandle.md   |   4 +-
 docs/docs/api/appkit/Interface.DatasetRow.md  |  22 ++
 .../appkit/Interface.DiscoveredEvalConfig.md  |  23 ++
 docs/docs/api/appkit/Interface.DriveResult.md |  25 ++
 docs/docs/api/appkit/Interface.EvalConfig.md  |  67 +++++
 .../api/appkit/Interface.EvalDefinition.md    |  28 ++
 docs/docs/api/appkit/Interface.EvalDriver.md  |  15 +
 docs/docs/api/appkit/Interface.EvalSummary.md |  10 +
 .../api/appkit/Interface.EvalWebServer.md     |  49 ++++
 .../Interface.ReadEvalDatasetOptions.md       |  31 +++
 .../api/appkit/Interface.RunEvalOptions.md    |  21 ++
 .../api/appkit/Interface.RunEvalsOptions.md   |  75 ++++-
 docs/docs/api/appkit/Interface.TestContext.md |  68 ++++-
 docs/docs/api/appkit/index.md                 |  74 ++---
 docs/docs/api/appkit/typedoc-sidebar.ts       | 262 +++++-------------
 25 files changed, 743 insertions(+), 259 deletions(-)
 create mode 100644 docs/docs/api/appkit/Function.discoverEvalConfigs.md
 create mode 100644 docs/docs/api/appkit/Function.findRootEvalConfig.md
 create mode 100644 docs/docs/api/appkit/Function.formatResultsJUnit.md
 create mode 100644 docs/docs/api/appkit/Function.formatResultsJson.md
 create mode 100644 docs/docs/api/appkit/Function.loadRootEvalConfig.md
 create mode 100644 docs/docs/api/appkit/Function.readEvalDataset.md
 create mode 100644 docs/docs/api/appkit/Function.resolveWorkspaceClient.md
 create mode 100644 docs/docs/api/appkit/Function.runBounded.md
 create mode 100644 docs/docs/api/appkit/Function.runWithRetries.md
 create mode 100644 docs/docs/api/appkit/Function.userTurns.md
 create mode 100644 docs/docs/api/appkit/Interface.DatasetRow.md
 create mode 100644 docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md
 create mode 100644 docs/docs/api/appkit/Interface.EvalConfig.md
 create mode 100644 docs/docs/api/appkit/Interface.EvalWebServer.md
 create mode 100644 docs/docs/api/appkit/Interface.ReadEvalDatasetOptions.md

diff --git a/docs/docs/api/appkit/Function.discoverEvalConfigs.md b/docs/docs/api/appkit/Function.discoverEvalConfigs.md
new file mode 100644
index 000000000..f350af5e0
--- /dev/null
+++ b/docs/docs/api/appkit/Function.discoverEvalConfigs.md
@@ -0,0 +1,20 @@
+# Function: discoverEvalConfigs()
+
+```ts
+function discoverEvalConfigs(rootDir: string): DiscoveredEvalConfig[];
+```
+
+Discover the per-agent `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at
+`<rootDir>/config/agents/<agent>/evals/evals.config.ts`. Config is per-agent:
+each agent's config applies only to that agent's evals. Agents without a
+config file are omitted. Returns a stable, sorted list.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `rootDir` | `string` |
+
+## Returns
+
+[`DiscoveredEvalConfig`](Interface.DiscoveredEvalConfig.md)[]
diff --git a/docs/docs/api/appkit/Function.findRootEvalConfig.md b/docs/docs/api/appkit/Function.findRootEvalConfig.md
new file mode 100644
index 000000000..2b6a4cb1b
--- /dev/null
+++ b/docs/docs/api/appkit/Function.findRootEvalConfig.md
@@ -0,0 +1,20 @@
+# Function: findRootEvalConfig()
+
+```ts
+function findRootEvalConfig(rootDir: string): string | undefined;
+```
+
+Path to the root `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at
+`<rootDir>/evals.config.ts`, or `undefined` when absent. The root config
+holds run-wide settings (`baseUrl`, `webServer`); it's distinct from the
+per-agent configs found by [discoverEvalConfigs](Function.discoverEvalConfigs.md).
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `rootDir` | `string` |
+
+## Returns
+
+`string` \| `undefined`
diff --git a/docs/docs/api/appkit/Function.formatResultsJUnit.md b/docs/docs/api/appkit/Function.formatResultsJUnit.md
new file mode 100644
index 000000000..de0e3df36
--- /dev/null
+++ b/docs/docs/api/appkit/Function.formatResultsJUnit.md
@@ -0,0 +1,20 @@
+# Function: formatResultsJUnit()
+
+```ts
+function formatResultsJUnit(results: EvalResult[]): string;
+```
+
+Render results as JUnit XML for standard CI test reporters: a single
+`<testsuite name="appkit-agent-evals">` with one `<testcase>` per result.
+Failures carry a `<failure>` (error or failing-gate summary); skips a
+`<skipped>`. All attribute/text values are XML-escaped.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `results` | [`EvalResult`](Interface.EvalResult.md)[] |
+
+## Returns
+
+`string`
diff --git a/docs/docs/api/appkit/Function.formatResultsJson.md b/docs/docs/api/appkit/Function.formatResultsJson.md
new file mode 100644
index 000000000..7cf11944a
--- /dev/null
+++ b/docs/docs/api/appkit/Function.formatResultsJson.md
@@ -0,0 +1,19 @@
+# Function: formatResultsJson()
+
+```ts
+function formatResultsJson(results: EvalResult[]): string;
+```
+
+Render results as a machine-readable JSON report (2-space indented):
+`{ summary: EvalSummary, results: EvalResult[] }`. Faithful to the types —
+every field present on a result round-trips.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `results` | [`EvalResult`](Interface.EvalResult.md)[] |
+
+## Returns
+
+`string`
diff --git a/docs/docs/api/appkit/Function.loadRootEvalConfig.md b/docs/docs/api/appkit/Function.loadRootEvalConfig.md
new file mode 100644
index 000000000..b3238a821
--- /dev/null
+++ b/docs/docs/api/appkit/Function.loadRootEvalConfig.md
@@ -0,0 +1,20 @@
+# Function: loadRootEvalConfig()
+
+```ts
+function loadRootEvalConfig(rootDir: string): Promise<EvalConfig | undefined>;
+```
+
+Load the root `evals.config.ts` under `rootDir` (the project root), or return
+`undefined` when there is none. This is the run-wide config carrying
+`baseUrl`/`webServer`; the CLI reads it to resolve options and manage the
+app-under-test lifecycle before calling [runEvalsInDir](Function.runEvalsInDir.md).
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `rootDir` | `string` |
+
+## Returns
+
+`Promise`\<[`EvalConfig`](Interface.EvalConfig.md) \| `undefined`\>
diff --git a/docs/docs/api/appkit/Function.readEvalDataset.md b/docs/docs/api/appkit/Function.readEvalDataset.md
new file mode 100644
index 000000000..5ca486b2b
--- /dev/null
+++ b/docs/docs/api/appkit/Function.readEvalDataset.md
@@ -0,0 +1,26 @@
+# Function: readEvalDataset()
+
+```ts
+function readEvalDataset(client: WorkspaceClient, options: ReadEvalDatasetOptions): Promise<DatasetRow[]>;
+```
+
+Read a Databricks managed evaluation dataset (a Unity Catalog table with
+`inputs`/`expectations` columns) into rows, over the public SQL Statement
+Execution API. Reuses SQLWarehouseConnector for submit/poll/transform
+— its result transform already JSON-parses string columns into objects, so
+`inputs`/`expectations` come back as records whether the table stores them as
+JSON strings or structs.
+
+The Python `mlflow.genai.datasets` API needs a Spark session (no TS
+equivalent), so we read the backing table directly.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `client` | `WorkspaceClient` |
+| `options` | [`ReadEvalDatasetOptions`](Interface.ReadEvalDatasetOptions.md) |
+
+## Returns
+
+`Promise`\<[`DatasetRow`](Interface.DatasetRow.md)[]\>
diff --git a/docs/docs/api/appkit/Function.resolveWorkspaceClient.md b/docs/docs/api/appkit/Function.resolveWorkspaceClient.md
new file mode 100644
index 000000000..1b80639b9
--- /dev/null
+++ b/docs/docs/api/appkit/Function.resolveWorkspaceClient.md
@@ -0,0 +1,21 @@
+# Function: resolveWorkspaceClient()
+
+```ts
+function resolveWorkspaceClient(options: ResolveDatabricksAuthOptions): WorkspaceClient | undefined;
+```
+
+Construct a Databricks `WorkspaceClient` for the eval runner — the object the
+SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit
+host+token builds a PAT client; otherwise the profile (or ambient config) is
+used and the SDK resolves credentials, minting OAuth as needed. Returns
+`undefined` if construction throws (missing/invalid config).
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`ResolveDatabricksAuthOptions`](Interface.ResolveDatabricksAuthOptions.md) |
+
+## Returns
+
+`WorkspaceClient` \| `undefined`
diff --git a/docs/docs/api/appkit/Function.runBounded.md b/docs/docs/api/appkit/Function.runBounded.md
new file mode 100644
index 000000000..1a08b36bf
--- /dev/null
+++ b/docs/docs/api/appkit/Function.runBounded.md
@@ -0,0 +1,34 @@
+# Function: runBounded()
+
+```ts
+function runBounded<T, R>(
+   tasks: readonly T[], 
+   limit: number, 
+worker: (task: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+Run `tasks` through a bounded worker pool and return their results in the
+SAME order as the input, regardless of completion order. Each task receives
+its input index so callers can key on it. `limit` is clamped to at least 1
+(and to the task count); at `limit === 1` this is a serial loop. Individual
+task rejections are surfaced per-slot via `settle` rather than aborting
+siblings — but eval tasks never reject (failures become results).
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `R` |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `tasks` | readonly `T`[] |
+| `limit` | `number` |
+| `worker` | (`task`: `T`, `index`: `number`) => `Promise`\<`R`\> |
+
+## Returns
+
+`Promise`\<`R`[]\>
diff --git a/docs/docs/api/appkit/Function.runWithRetries.md b/docs/docs/api/appkit/Function.runWithRetries.md
new file mode 100644
index 000000000..5b4660a74
--- /dev/null
+++ b/docs/docs/api/appkit/Function.runWithRetries.md
@@ -0,0 +1,22 @@
+# Function: runWithRetries()
+
+```ts
+function runWithRetries(retries: number, attempt: (attemptNumber: number) => Promise<EvalResult>): Promise<EvalResult>;
+```
+
+Run `attempt` up to `1 + retries` times, stopping as soon as it returns a
+result without an `error` (infra failures — thrown errors or timeouts — set
+`error`; assertion failures do not, so a failed-but-completed eval is returned
+on the first try and never retried). Returns the last result when every
+attempt errored. `retries` below 0 is treated as 0.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `retries` | `number` |
+| `attempt` | (`attemptNumber`: `number`) => `Promise`\<[`EvalResult`](Interface.EvalResult.md)\> |
+
+## Returns
+
+`Promise`\<[`EvalResult`](Interface.EvalResult.md)\>
diff --git a/docs/docs/api/appkit/Function.userTurns.md b/docs/docs/api/appkit/Function.userTurns.md
new file mode 100644
index 000000000..1ad9c8706
--- /dev/null
+++ b/docs/docs/api/appkit/Function.userTurns.md
@@ -0,0 +1,26 @@
+# Function: userTurns()
+
+```ts
+function userTurns(input: Record<string, unknown>): string[];
+```
+
+Extract every user-message content, in order, from an MLflow
+`{"messages":[{"role":"user","content":"..."}]}` input. A dataset row can
+carry a full multi-turn conversation; replaying these against one thread (one
+`t.send` per returned string) lets the agent see the accumulating history.
+
+Only `role === "user"` turns are returned — any interleaved `assistant`/
+`system` messages in the row are ignored, since the agent generates its own
+responses; you never inject the dataset's assistant turns. A single-user-turn
+row yields a one-element array (backward compatible); a row with no `messages`
+yields `[]`.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | `Record`\<`string`, `unknown`\> |
+
+## Returns
+
+`string`[]
diff --git a/docs/docs/api/appkit/Interface.AssertionHandle.md b/docs/docs/api/appkit/Interface.AssertionHandle.md
index 02e3c746b..0e640960b 100644
--- a/docs/docs/api/appkit/Interface.AssertionHandle.md
+++ b/docs/docs/api/appkit/Interface.AssertionHandle.md
@@ -12,7 +12,9 @@ metric; `.atLeast(n)` is a soft, score-thresholded assertion.
 atLeast(threshold: number): AssertionHandle;
 ```
 
-Soft assertion that passes only when the score is at least `threshold`.
+Set the pass threshold for a scored assertion: it passes only when the
+score is at least `threshold`. Keeps the current severity (gate unless also
+chained with `.soft()`).
 
 #### Parameters
 
diff --git a/docs/docs/api/appkit/Interface.DatasetRow.md b/docs/docs/api/appkit/Interface.DatasetRow.md
new file mode 100644
index 000000000..32644c2dc
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.DatasetRow.md
@@ -0,0 +1,22 @@
+# Interface: DatasetRow
+
+One row of a managed evaluation dataset. `inputs` are the kwargs passed to the
+agent for the turn; `expectations` (when present) is the row's ground truth /
+guidelines. Mirrors the `{inputs, expectations}` shape of `mlflow.genai`
+datasets and of the Unity Catalog table backing a managed eval dataset.
+
+## Properties
+
+### expectations?
+
+```ts
+optional expectations: Record<string, unknown>;
+```
+
+***
+
+### inputs
+
+```ts
+inputs: Record<string, unknown>;
+```
diff --git a/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md b/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md
new file mode 100644
index 000000000..7b4f2a831
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md
@@ -0,0 +1,23 @@
+# Interface: DiscoveredEvalConfig
+
+A per-agent `evals.config.ts` found under `config/agents/<agent>/evals/`.
+
+## Properties
+
+### agent
+
+```ts
+agent: string;
+```
+
+The agent id whose evals this config applies to.
+
+***
+
+### file
+
+```ts
+file: string;
+```
+
+Absolute path to the `evals.config.ts` file.
diff --git a/docs/docs/api/appkit/Interface.DriveResult.md b/docs/docs/api/appkit/Interface.DriveResult.md
index 15625c1ac..f168e875a 100644
--- a/docs/docs/api/appkit/Interface.DriveResult.md
+++ b/docs/docs/api/appkit/Interface.DriveResult.md
@@ -34,6 +34,31 @@ Whether the turn completed without an agent/stream error.
 
 ***
 
+### toolCallDetails
+
+```ts
+toolCallDetails: {
+  args: Record<string, unknown>;
+  name: string;
+}[];
+```
+
+Tool calls with their parsed arguments, in call order.
+
+#### args
+
+```ts
+args: Record<string, unknown>;
+```
+
+#### name
+
+```ts
+name: string;
+```
+
+***
+
 ### toolCalls
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.EvalConfig.md b/docs/docs/api/appkit/Interface.EvalConfig.md
new file mode 100644
index 000000000..4d8fd8519
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.EvalConfig.md
@@ -0,0 +1,67 @@
+# Interface: EvalConfig
+
+Eval config from `evals.config.ts` (via [defineEvalConfig](Function.defineEvalConfig.md)).
+
+Two scopes share this shape: a **root** `evals.config.ts` (project root) may
+set run-wide settings — `baseUrl` and `webServer` — plus defaults for
+`maxConcurrency`/`timeoutMs`; a **per-agent** `config/agents/<id>/evals/evals.config.ts`
+sets only that agent's `maxConcurrency`/`timeoutMs` overrides (`baseUrl`/
+`webServer` there are ignored — server lifecycle is run-wide).
+
+## Properties
+
+### baseUrl?
+
+```ts
+optional baseUrl: string;
+```
+
+Base URL of the app to drive (root config only). Overridden by `--url`.
+
+***
+
+### judge?
+
+```ts
+optional judge: {
+  model?: string;
+};
+```
+
+LLM judge config. Defaults to the agent's own serving endpoint.
+
+#### model?
+
+```ts
+optional model: string;
+```
+
+***
+
+### maxConcurrency?
+
+```ts
+optional maxConcurrency: number;
+```
+
+Max evals to run concurrently.
+
+***
+
+### timeoutMs?
+
+```ts
+optional timeoutMs: number;
+```
+
+Default per-eval timeout.
+
+***
+
+### webServer?
+
+```ts
+optional webServer: EvalWebServer;
+```
+
+Auto-start the app under test (root config only).
diff --git a/docs/docs/api/appkit/Interface.EvalDefinition.md b/docs/docs/api/appkit/Interface.EvalDefinition.md
index 3bf035507..cea1d47e7 100644
--- a/docs/docs/api/appkit/Interface.EvalDefinition.md
+++ b/docs/docs/api/appkit/Interface.EvalDefinition.md
@@ -14,6 +14,34 @@ Target agent id. Defaults to the eval's parent `server/agents/<id>` dir.
 
 ***
 
+### dataset?
+
+```ts
+optional dataset: {
+  limit?: number;
+  table: string;
+};
+```
+
+Run this eval once per row of a Databricks managed evaluation dataset (a
+Unity Catalog `catalog.schema.table` with `inputs`/`expectations` columns).
+Each row is bound to `t.input`/`t.expected`. Requires the runner to have a
+workspace client + warehouse (`--warehouse`). Omit for a single-run eval.
+
+#### limit?
+
+```ts
+optional limit: number;
+```
+
+#### table
+
+```ts
+table: string;
+```
+
+***
+
 ### description?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.EvalDriver.md b/docs/docs/api/appkit/Interface.EvalDriver.md
index 69d81a05a..6cf961dda 100644
--- a/docs/docs/api/appkit/Interface.EvalDriver.md
+++ b/docs/docs/api/appkit/Interface.EvalDriver.md
@@ -5,6 +5,21 @@ app's agents endpoint; future drivers (in-process) implement the same shape.
 
 ## Methods
 
+### reset()?
+
+```ts
+optional reset(): void;
+```
+
+Drop the current conversation so the next `send` starts a fresh thread.
+Optional: drivers without a session concept omit it.
+
+#### Returns
+
+`void`
+
+***
+
 ### send()
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.EvalSummary.md b/docs/docs/api/appkit/Interface.EvalSummary.md
index 3c8fc1e6e..11a682148 100644
--- a/docs/docs/api/appkit/Interface.EvalSummary.md
+++ b/docs/docs/api/appkit/Interface.EvalSummary.md
@@ -28,6 +28,16 @@ passed: number;
 
 ***
 
+### passRate
+
+```ts
+passRate: number;
+```
+
+Fraction of scored (non-skipped) evals that passed, 0..1 (1 when none scored).
+
+***
+
 ### skipped
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.EvalWebServer.md b/docs/docs/api/appkit/Interface.EvalWebServer.md
new file mode 100644
index 000000000..f220ad6ae
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.EvalWebServer.md
@@ -0,0 +1,49 @@
+# Interface: EvalWebServer
+
+Auto-start config for the app under test, à la Playwright's `webServer`. When
+set in a root `evals.config.ts`, the CLI boots the app before running evals
+and tears it down after — so you don't have to start the server by hand.
+
+## Properties
+
+### command
+
+```ts
+command: string;
+```
+
+Shell command that starts the app, e.g. `"npm run dev"`.
+
+***
+
+### reuseExisting?
+
+```ts
+optional reuseExisting: boolean;
+```
+
+When `true` (default), reuse a server already answering at `url` instead of
+spawning one — so a running `dev` server is used as-is. Set `false` to
+always spawn a fresh server.
+
+***
+
+### timeoutMs?
+
+```ts
+optional timeoutMs: number;
+```
+
+How long to wait for `url` to answer before giving up. Defaults to 60s.
+
+***
+
+### url?
+
+```ts
+optional url: string;
+```
+
+URL polled until it answers before evals start. Defaults to the run's
+`baseUrl` (`--url`). Readiness = any HTTP response (a 404 still proves the
+server is up).
diff --git a/docs/docs/api/appkit/Interface.ReadEvalDatasetOptions.md b/docs/docs/api/appkit/Interface.ReadEvalDatasetOptions.md
new file mode 100644
index 000000000..f6411df51
--- /dev/null
+++ b/docs/docs/api/appkit/Interface.ReadEvalDatasetOptions.md
@@ -0,0 +1,31 @@
+# Interface: ReadEvalDatasetOptions
+
+## Properties
+
+### limit?
+
+```ts
+optional limit: number;
+```
+
+Optional row cap.
+
+***
+
+### table
+
+```ts
+table: string;
+```
+
+Fully-qualified UC table: `catalog.schema.table`.
+
+***
+
+### warehouseId
+
+```ts
+warehouseId: string;
+```
+
+SQL warehouse id to run the read against.
diff --git a/docs/docs/api/appkit/Interface.RunEvalOptions.md b/docs/docs/api/appkit/Interface.RunEvalOptions.md
index 16a6b8190..f89837405 100644
--- a/docs/docs/api/appkit/Interface.RunEvalOptions.md
+++ b/docs/docs/api/appkit/Interface.RunEvalOptions.md
@@ -22,6 +22,16 @@ Stable id for the eval (e.g. its file path relative to the evals dir).
 
 ***
 
+### row?
+
+```ts
+optional row: DatasetRow;
+```
+
+Dataset row bound to `t.input`/`t.expected` for dataset-driven evals.
+
+***
+
 ### strict?
 
 ```ts
@@ -29,3 +39,14 @@ optional strict: boolean;
 ```
 
 When true, soft assertion failures also fail the eval.
+
+***
+
+### timeoutMs?
+
+```ts
+optional timeoutMs: number;
+```
+
+Runner-level default per-eval timeout (ms). `def.timeoutMs` wins over this;
+when both are unset the eval runs unbounded (current behavior).
diff --git a/docs/docs/api/appkit/Interface.RunEvalsOptions.md b/docs/docs/api/appkit/Interface.RunEvalsOptions.md
index 48df08c07..c1c7ec78a 100644
--- a/docs/docs/api/appkit/Interface.RunEvalsOptions.md
+++ b/docs/docs/api/appkit/Interface.RunEvalsOptions.md
@@ -12,19 +12,6 @@ Base URL of the running app to drive, e.g. `http://localhost:3000`.
 
 ***
 
-### concurrency?
-
-```ts
-optional concurrency: number;
-```
-
-Max evals to drive concurrently. Each eval opens one stream to the app as
-the same user, so keep this at or below the app's
-`maxConcurrentStreamsPerUser` (default 5) or the surplus streams hit the
-429 guard. Defaults to 4; clamped to `[1, total]`.
-
-***
-
 ### filter?
 
 ```ts
@@ -78,6 +65,18 @@ token: string;
 
 ***
 
+### maxConcurrency?
+
+```ts
+optional maxConcurrency: number;
+```
+
+Max evals/dataset rows to drive concurrently. Defaults to `1` (serial).
+Values below 1 are clamped to 1. Output order is preserved regardless.
+Wins over an agent's `evals.config.ts` `maxConcurrency`.
+
+***
+
 ### mlflow?
 
 ```ts
@@ -151,13 +150,26 @@ Progress callback, invoked as evals are discovered, started, and finished.
 
 ***
 
+### retries?
+
+```ts
+optional retries: number;
+```
+
+Re-run an eval up to this many extra times when it fails on an
+infrastructure error (a thrown error or timeout — `result.error` set), to
+absorb transient turn/stream flakiness. Assertion failures are NEVER
+retried (a wrong reply is real signal, not flake). Defaults to `0`.
+
+***
+
 ### rootDir?
 
 ```ts
 optional rootDir: string;
 ```
 
-Project root containing `server/agents/`. Defaults to `process.cwd()`.
+Project root containing `config/agents/`. Defaults to `process.cwd()`.
 
 ***
 
@@ -171,10 +183,43 @@ Soft assertion failures also fail the eval.
 
 ***
 
+### tags?
+
+```ts
+optional tags: string[];
+```
+
+Only run evals whose `tags` intersect this list. Empty/undefined runs all.
+Tags live on the eval def, so filtering happens after each file is loaded.
+
+***
+
 ### timeoutMs?
 
 ```ts
 optional timeoutMs: number;
 ```
 
-Per-turn wall-clock timeout (ms) before a turn is failed. Defaults to 120s.
+Default per-eval timeout (ms). A per-eval `def.timeoutMs` overrides it.
+Wins over an agent's `evals.config.ts` `timeoutMs`.
+
+***
+
+### warehouseId?
+
+```ts
+optional warehouseId: string;
+```
+
+SQL warehouse id used to read managed evaluation datasets.
+
+***
+
+### workspaceClient?
+
+```ts
+optional workspaceClient: WorkspaceClient;
+```
+
+Workspace client used to read managed evaluation datasets (for evals that
+declare `dataset`). Required alongside [warehouseId](#warehouseid) for those evals.
diff --git a/docs/docs/api/appkit/Interface.TestContext.md b/docs/docs/api/appkit/Interface.TestContext.md
index e21156235..ab2c549a1 100644
--- a/docs/docs/api/appkit/Interface.TestContext.md
+++ b/docs/docs/api/appkit/Interface.TestContext.md
@@ -4,6 +4,28 @@ The `t` context passed to an eval's `test` function.
 
 ## Properties
 
+### expected
+
+```ts
+readonly expected: Record<string, unknown> | undefined;
+```
+
+The current dataset row's `expectations` (ground truth / guidelines), or
+`undefined` when the row has none or the eval isn't dataset-driven.
+
+***
+
+### input
+
+```ts
+readonly input: Record<string, unknown>;
+```
+
+The current dataset row's `inputs` when the eval is dataset-driven (see
+[EvalDefinition.dataset](Interface.EvalDefinition.md#dataset)); `{}` for a plain single-run eval.
+
+***
+
 ### judge
 
 ```ts
@@ -15,9 +37,10 @@ judge: {
 ```
 
 LLM-as-judge scoring of the last reply (via autoevals → a Databricks judge
-model). Each returns a scored, soft-by-default assertion; chain `.atLeast(n)`
-to set the pass threshold or `.gate()` to make it a hard gate. Requires the
-judge to be configured (`--judge-model`).
+model). Each returns a scored assertion that gates by default (a miss fails
+the eval); chain `.atLeast(n)` to change the pass threshold or `.soft()` to
+demote to a tracked-only metric. Requires the judge to be configured
+(`--judge-model`).
 
 #### closedQA()
 
@@ -125,6 +148,29 @@ Assert a tool was called during the run (gate by default).
 
 ***
 
+### calledToolWith()
+
+```ts
+calledToolWith(name: string, expected: Record<string, unknown>): AssertionHandle;
+```
+
+Assert a tool was called with arguments that deep-contain `expected`: every
+key in `expected` must equal the actual argument (recursively for nested
+objects), so extra arguments are ignored. Gate by default.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `name` | `string` |
+| `expected` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+[`AssertionHandle`](Interface.AssertionHandle.md)
+
+***
+
 ### check()
 
 ```ts
@@ -146,6 +192,22 @@ Assert a value against a matcher, e.g. `t.check(t.reply, includes("Sunny"))`.
 
 ***
 
+### reset()
+
+```ts
+reset(): void;
+```
+
+Start a fresh conversation: the next `send` opens a new thread with no
+history. Use to run several independent one-shot checks in one test.
+Consecutive `send`s (without a `reset`) stay in one multi-turn conversation.
+
+#### Returns
+
+`void`
+
+***
+
 ### send()
 
 ```ts
diff --git a/docs/docs/api/appkit/index.md b/docs/docs/api/appkit/index.md
index 42afc4a50..c3fc41620 100644
--- a/docs/docs/api/appkit/index.md
+++ b/docs/docs/api/appkit/index.md
@@ -27,7 +27,6 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [PolicyDeniedError](Class.PolicyDeniedError.md) | Thrown when a policy denies an action. |
 | [ResourceRegistry](Class.ResourceRegistry.md) | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only. |
 | [ServerError](Class.ServerError.md) | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc. |
-| [SupervisorApiAdapter](Class.SupervisorApiAdapter.md) | Adapter that calls the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`). |
 | [TunnelError](Class.TunnelError.md) | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc. |
 | [ValidationError](Class.ValidationError.md) | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches. |
 
@@ -49,26 +48,25 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [CacheConfig](Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
 | [CustomJudgeSpec](Interface.CustomJudgeSpec.md) | A custom LLM-judge definition: a prompt template and choice→score mapping. |
 | [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
-| [DatabaseRegistry](Interface.DatabaseRegistry.md) | CANONICAL augmentation target. Empty by default; the generated `database.d.ts` augments it via `declare module "@databricks/appkit" { interface DatabaseRegistry { ... } }`. |
 | [DatabricksAuth](Interface.DatabricksAuth.md) | Resolved Databricks host + bearer token for the eval runner's REST calls. |
-| [DiscoveredEval](Interface.DiscoveredEval.md) | An eval file found under `server/agents/<agent>/evals/`. |
+| [DatasetRow](Interface.DatasetRow.md) | One row of a managed evaluation dataset. `inputs` are the kwargs passed to the agent for the turn; `expectations` (when present) is the row's ground truth / guidelines. Mirrors the `{inputs, expectations}` shape of `mlflow.genai` datasets and of the Unity Catalog table backing a managed eval dataset. |
+| [DiscoveredEval](Interface.DiscoveredEval.md) | An eval file found under `config/agents/<agent>/evals/`. |
+| [DiscoveredEvalConfig](Interface.DiscoveredEvalConfig.md) | A per-agent `evals.config.ts` found under `config/agents/<agent>/evals/`. |
 | [DriveResult](Interface.DriveResult.md) | What a driver returns for a single `t.send`. |
 | [EndpointConfig](Interface.EndpointConfig.md) | - |
+| [EvalConfig](Interface.EvalConfig.md) | Eval config from `evals.config.ts` (via [defineEvalConfig](Function.defineEvalConfig.md)). |
 | [EvalDefinition](Interface.EvalDefinition.md) | A single eval, default-exported from a `*.eval.ts` file. |
 | [EvalDriver](Interface.EvalDriver.md) | Abstraction over how the agent is driven. The HTTP driver posts to a running app's agents endpoint; future drivers (in-process) implement the same shape. |
 | [EvalResult](Interface.EvalResult.md) | The outcome of running one eval. |
 | [EvalRunSummary](Interface.EvalRunSummary.md) | - |
 | [EvalSummary](Interface.EvalSummary.md) | - |
+| [EvalWebServer](Interface.EvalWebServer.md) | Auto-start config for the app under test, à la Playwright's `webServer`. When set in a root `evals.config.ts`, the CLI boots the app before running evals and tears it down after — so you don't have to start the server by hand. |
 | [FilePolicyUser](Interface.FilePolicyUser.md) | Minimal user identity passed to the policy function. |
 | [FileResource](Interface.FileResource.md) | Describes the file or directory being acted upon. |
 | [FunctionTool](Interface.FunctionTool.md) | - |
 | [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
-| [GenerationParams](Interface.GenerationParams.md) | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates. |
-| [HostedSupervisorTool](Interface.HostedSupervisorTool.md) | Tagged record returned by every [supervisorTools](Variable.supervisorTools.md) factory. The `__kind` discriminator lets the agents plugin (and standalone `runAgent`) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use `type: "genie-space"` hyphenated, vs SA's `type: "genie_space"` underscored). |
 | [HttpDriverOptions](Interface.HttpDriverOptions.md) | - |
-| [IAiSearchConfig](Interface.IAiSearchConfig.md) | Base configuration interface for AppKit plugins |
 | [IJobsConfig](Interface.IJobsConfig.md) | Configuration for the Jobs plugin. |
-| [IndexConfig](Interface.IndexConfig.md) | - |
 | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
 | [JobAPI](Interface.JobAPI.md) | User-facing API for a single configured job. |
 | [JobConfig](Interface.JobConfig.md) | Per-job configuration options. |
@@ -85,11 +83,11 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [PluginToolkitProvider](Interface.PluginToolkitProvider.md) | Minimum shape every entry in the [Plugins](TypeAlias.Plugins.md) map must expose. Core plugins (analytics, files, genie, lakebase) implement this directly via their `.toolkit()` method. The agents plugin and standalone `runAgent` synthesize this shape for any registered plugin that doesn't implement `.toolkit()` directly (falling back to `getAgentTools()` walking). |
 | [PostResult](Interface.PostResult.md) | Structured result for a best-effort POST that must not throw. |
 | [PromptContext](Interface.PromptContext.md) | Context passed to `baseSystemPrompt` callbacks. |
+| [ReadEvalDatasetOptions](Interface.ReadEvalDatasetOptions.md) | - |
 | [RegisteredAgent](Interface.RegisteredAgent.md) | - |
 | [ReportOutcome](Interface.ReportOutcome.md) | - |
 | [RequestedClaims](Interface.RequestedClaims.md) | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables |
 | [RequestedResource](Interface.RequestedResource.md) | Resource to request permissions for in Unity Catalog |
-| [RerankerConfig](Interface.RerankerConfig.md) | - |
 | [ResolveDatabricksAuthOptions](Interface.ResolveDatabricksAuthOptions.md) | - |
 | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
 | [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). |
@@ -97,15 +95,9 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [RunAgentResult](Interface.RunAgentResult.md) | - |
 | [RunEvalOptions](Interface.RunEvalOptions.md) | - |
 | [RunEvalsOptions](Interface.RunEvalsOptions.md) | - |
-| [Schema](Interface.Schema.md) | One finalized schema. `TTableName` keeps the declared names in the type, so configuration that addresses a table by name is checked against the schema it was written for. Code that accepts any schema uses the default. |
-| [SearchRequest](Interface.SearchRequest.md) | - |
-| [SearchResponse](Interface.SearchResponse.md) | - |
-| [SearchResult](Interface.SearchResult.md) | - |
 | [ServingEndpointEntry](Interface.ServingEndpointEntry.md) | Shape of a single registry entry. |
 | [ServingEndpointRegistry](Interface.ServingEndpointRegistry.md) | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint. |
 | [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. |
-| [SupervisorApiAdapterOptions](Interface.SupervisorApiAdapterOptions.md) | - |
-| [SupervisorExtension](Interface.SupervisorExtension.md) | Shape of the value at `AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]`. The agents plugin / `runAgent` build this from the tool index; advanced callers invoking `adapter.run(...)` directly populate it themselves. |
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
 | [TestContext](Interface.TestContext.md) | The `t` context passed to an eval's `test` function. |
 | [Thread](Interface.Thread.md) | - |
@@ -117,28 +109,24 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [ToolkitOptions](Interface.ToolkitOptions.md) | - |
 | [ToolProvider](Interface.ToolProvider.md) | - |
 | [ValidationResult](Interface.ValidationResult.md) | Result of validating all registered resources against the environment. |
-| [WorkspaceClient](Interface.WorkspaceClient.md) | AppKit's workspace client facade. Mirrors the multi-client shape of the modular Databricks SDK: each service is its own accessor, so services can be migrated one at a time behind this stable interface. |
-| [WorkspaceClientLike](Interface.WorkspaceClientLike.md) | Structural shape of a Databricks SDK client used by [fromSupervisorApi](Function.fromSupervisorApi.md). Only what we need: `apiClient.request` for streaming and `config.ensureResolved` to materialise the host/credentials. |
-| [WorkspaceClientOptions](Interface.WorkspaceClientOptions.md) | Options used to construct the wrapper. Mirrors the subset of the old SDK's `Config` + `ClientOptions` that AppKit relies on today; we deliberately do NOT re-expose every old-SDK config knob. |
 
 ## Type Aliases
 
 | Type Alias | Description |
 | ------ | ------ |
 | [AgentEvent](TypeAlias.AgentEvent.md) | - |
-| [AgentTool](TypeAlias.AgentTool.md) | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), toolkit references from plugins (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools (`supervisorTools.*`). |
+| [AgentTool](TypeAlias.AgentTool.md) | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), or toolkit references from plugins (`analytics().toolkit()`). |
 | [AgentTools](TypeAlias.AgentTools.md) | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc. |
 | [AgentToolsFn](TypeAlias.AgentToolsFn.md) | Function form of `AgentDefinition.tools`. Receives the typed [Plugins](TypeAlias.Plugins.md) map and returns a tool record. Invoked exactly once at setup (or once per `runAgent` call in standalone mode); the result is cached as the agent's resolved tool record. |
 | [BaseSystemPromptOption](TypeAlias.BaseSystemPromptOption.md) | - |
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
-| [DatabaseExports](TypeAlias.DatabaseExports.md) | Typed database API published by the plugin. |
 | [EvalProgress](TypeAlias.EvalProgress.md) | - |
 | [ExecutionResult](TypeAlias.ExecutionResult.md) | Discriminated union for plugin execution results. |
 | [FileAction](TypeAlias.FileAction.md) | Every action the files plugin can perform. |
 | [FilePolicy](TypeAlias.FilePolicy.md) | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
 | [HostedTool](TypeAlias.HostedTool.md) | - |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
-| [IDatabaseConfig](TypeAlias.IDatabaseConfig.md) | Configuration for one schema-bound DatabasePlugin instance. |
+| [JobHandle](TypeAlias.JobHandle.md) | Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`. |
 | [JobsExport](TypeAlias.JobsExport.md) | Public API shape of the jobs plugin. Callable to select a job by key. |
 | [Matcher](TypeAlias.Matcher.md) | A deterministic matcher: inspects a string value and returns a result. |
 | [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
@@ -146,10 +134,8 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [ResolvedToolEntry](TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
 | [ResourceFieldEntry](TypeAlias.ResourceFieldEntry.md) | - |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
-| [SearchFilters](TypeAlias.SearchFilters.md) | - |
 | [ServingFactory](TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. |
 | [Severity](TypeAlias.Severity.md) | Whether an assertion fails the eval (`gate`) or is tracked only (`soft`). |
-| [SupervisorTool](TypeAlias.SupervisorTool.md) | Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body. |
 | [ToolRegistry](TypeAlias.ToolRegistry.md) | - |
 | [ToPlugin](TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
 
@@ -157,12 +143,9 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 
 | Variable | Description |
 | ------ | ------ |
-| [agents](Variable.agents.md) | Plugin factory for the agents plugin. Discovers agents from `server/agents/<id>/agent.{ts,md}` by default (markdown still in `config/agents/` is read as a deprecated fallback), resolves toolkits/tools from registered plugins, exposes the `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
-| [aiSearch](Variable.aiSearch.md) | - |
+| [agents](Variable.agents.md) | Plugin factory for the agents plugin. Reads `config/agents/*.md` by default, resolves toolkits/tools from registered plugins, exposes `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
 | [READ\_ACTIONS](Variable.READ_ACTIONS.md) | Actions that only read data. |
 | [sql](Variable.sql.md) | SQL helper namespace |
-| [SUPERVISOR\_EXTENSION\_KEY](Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads. |
-| [supervisorTools](Variable.supervisorTools.md) | Concise factories for declaring Supervisor API tools. |
 | [WRITE\_ACTIONS](Variable.WRITE_ACTIONS.md) | Actions that mutate data. |
 
 ## Functions
@@ -172,35 +155,30 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [agentIdFromMarkdownPath](Function.agentIdFromMarkdownPath.md) | Derives the logical agent id from a markdown path. When the file is named `agent.md`, the id is the parent directory name (folder-based layout); otherwise the id is the file stem (e.g. legacy single-file paths). |
 | [appKitServingTypesPlugin](Function.appKitServingTypesPlugin.md) | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation. |
 | [appKitTypesPlugin](Function.appKitTypesPlugin.md) | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood. |
-| [bigid](Function.bigid.md) | - |
-| [bigint](Function.bigint.md) | - |
-| [boolean](Function.boolean.md) | - |
-| [buildAssessments](Function.buildAssessments.md) | - |
+| [buildAssessments](Function.buildAssessments.md) | Build the Feedback assessments for an eval result: one per assertion (judge assertions tagged `LLM_JUDGE` with their numeric score + rationale, so they render as judge feedback in MLflow) plus an overall `appkit_eval` pass/fail. Returns [] when there's no trace to attach to or the eval was skipped. |
 | [configureJudge](Function.configureJudge.md) | Configure the judge once. Sets the OpenAI-compatible client env autoevals reads and the default judge model. No-op-safe: on failure, judging stays disabled and [isJudgeConfigured](Function.isJudgeConfigured.md) returns false. |
-| [createAgent](Function.createAgent.md) | Pure factory for agent definitions: cycle-detects the sub-agent graph and returns the same object, stamped with a non-enumerable AGENT\_BRAND so discovery recognizes it. Safe at module top-level; no adapter is built. Don't `Object.freeze` the definition before passing it in — the brand is written onto the argument. |
+| [createAgent](Function.createAgent.md) | Pure factory for agent definitions. Returns the passed-in definition after cycle-detecting the sub-agent graph. Accepts the full `AgentDefinition` shape and is safe to call at module top-level. |
 | [createApp](Function.createApp.md) | Bootstraps AppKit with the provided configuration. |
 | [createHttpDriver](Function.createHttpDriver.md) | Drives an agent by POSTing to a running app's chat endpoint and parsing the SSE response. Keeps the thread id across `send`s so multi-turn evals share a conversation. Agent/stream errors surface as `succeeded: false` rather than throwing, so `t.succeeded()` can assert on them. |
 | [createLakebasePool](Function.createLakebasePool.md) | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry. |
 | [createLakebasePoolManager](Function.createLakebasePoolManager.md) | Create a pool manager that maintains per-key Lakebase connection pools. |
-| [createWorkspaceClient](Function.createWorkspaceClient.md) | Construct an AppKit workspace client. |
-| [database](Function.database.md) | Create a typed database plugin registration for a finalized schema. |
-| [defineEval](Function.defineEval.md) | Define an agent eval. Default-export the result from a `server/agents/<id>/evals/*.eval.ts` file. |
-| [defineManifest](Function.defineManifest.md) | Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](Interface.PluginManifest.md). |
-| [defineSchema](Function.defineSchema.md) | Compile one declared schema. The returned type keeps the table names the builder returned, so `crudRoutes` and `hooks` can name only real tables. |
+| [defineEval](Function.defineEval.md) | Define an agent eval. Default-export the result from a `config/agents/<id>/evals/*.eval.ts` file. |
+| [defineEvalConfig](Function.defineEvalConfig.md) | Define per-directory eval config. Default-export from `evals.config.ts`. |
 | [defineTool](Function.defineTool.md) | Defines a single tool entry for a plugin's internal registry. |
-| [discoverEvalFiles](Function.discoverEvalFiles.md) | Discover evals under `<rootDir>/server/agents/<agent>/evals/` — co-located with each agent's `agent.{md,ts}` (same folder-per-agent layout the agents plugin discovers). The agent id is the folder name; the eval id is the file path relative to that evals dir with `.eval.ts` stripped. Sorted + stable. |
-| [enumColumn](Function.enumColumn.md) | - |
+| [discoverEvalConfigs](Function.discoverEvalConfigs.md) | Discover the per-agent `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at `<rootDir>/config/agents/<agent>/evals/evals.config.ts`. Config is per-agent: each agent's config applies only to that agent's evals. Agents without a config file are omitted. Returns a stable, sorted list. |
+| [discoverEvalFiles](Function.discoverEvalFiles.md) | Discover evals under `<rootDir>/config/agents/<agent>/evals/`. The agent id is the directory name; the eval id is the file path relative to that evals dir with `.eval.ts` stripped. Returns a stable, sorted list. |
 | [equals](Function.equals.md) | Passes when the value equals `expected` exactly. |
 | [evalGlyph](Function.evalGlyph.md) | Status glyph for a single eval result. |
 | [executeFromRegistry](Function.executeFromRegistry.md) | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn. |
 | [extractServingEndpoints](Function.extractServingEndpoints.md) | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings. |
+| [findRootEvalConfig](Function.findRootEvalConfig.md) | Path to the root `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at `<rootDir>/evals.config.ts`, or `undefined` when absent. The root config holds run-wide settings (`baseUrl`, `webServer`); it's distinct from the per-agent configs found by [discoverEvalConfigs](Function.discoverEvalConfigs.md). |
 | [findServerFile](Function.findServerFile.md) | Find the server entry file by checking candidate paths in order. |
-| [fk](Function.fk.md) | Declare foreign-key to another column. |
 | [formatEvalDetail](Function.formatEvalDetail.md) | Indented detail lines for a failing eval (error + failing assertions). |
 | [formatEvalHeadline](Function.formatEvalHeadline.md) | The one-line header for a single eval result (no failure detail). |
 | [formatEvalResults](Function.formatEvalResults.md) | Render all results as a human-readable console report (non-streaming). |
+| [formatResultsJson](Function.formatResultsJson.md) | Render results as a machine-readable JSON report (2-space indented): `{ summary: EvalSummary, results: EvalResult[] }`. Faithful to the types — every field present on a result round-trips. |
+| [formatResultsJUnit](Function.formatResultsJUnit.md) | Render results as JUnit XML for standard CI test reporters: a single `<testsuite name="appkit-agent-evals">` with one `<testcase>` per result. Failures carry a `<failure>` (error or failing-gate summary); skips a `<skipped>`. All attribute/text values are XML-escaped. |
 | [formatSummaryLine](Function.formatSummaryLine.md) | The final PASS/FAIL summary line. |
-| [fromSupervisorApi](Function.fromSupervisorApi.md) | Creates an [AgentAdapter](Interface.AgentAdapter.md) backed by the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`). |
 | [functionToolToDefinition](Function.functionToolToDefinition.md) | - |
 | [generateDatabaseCredential](Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API. |
 | [getExecutionContext](Function.getExecutionContext.md) | Get the current execution context. |
@@ -210,32 +188,30 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [getResourceRequirements](Function.getResourceRequirements.md) | Gets the resource requirements from a plugin's manifest. |
 | [getUsernameWithApiLookup](Function.getUsernameWithApiLookup.md) | Resolves the PostgreSQL username for a Lakebase connection. |
 | [getWorkspaceClient](Function.getWorkspaceClient.md) | Get workspace client from config or SDK default auth chain |
-| [id](Function.id.md) | - |
 | [includes](Function.includes.md) | Passes when the value contains `substring`. |
-| [integer](Function.integer.md) | - |
 | [isFunctionTool](Function.isFunctionTool.md) | - |
 | [isHostedTool](Function.isHostedTool.md) | - |
 | [isJudgeConfigured](Function.isJudgeConfigured.md) | - |
 | [isSQLTypeMarker](Function.isSQLTypeMarker.md) | Type guard to check if a value is a SQL type marker |
-| [isSupervisorTool](Function.isSupervisorTool.md) | Type guard for [HostedSupervisorTool](Interface.HostedSupervisorTool.md). Used by the agents plugin (`buildToolIndex`) and standalone `runAgent` (`classifyTool`) to route supervisor-hosted tools to the extensions payload rather than the adapter's `tools` array. |
 | [isToolkitEntry](Function.isToolkitEntry.md) | Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record. |
-| [jsonb](Function.jsonb.md) | - |
 | [loadAgentFromFile](Function.loadAgentFromFile.md) | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library. |
 | [loadAgentsFromDir](Function.loadAgentsFromDir.md) | Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist. |
+| [loadRootEvalConfig](Function.loadRootEvalConfig.md) | Load the root `evals.config.ts` under `rootDir` (the project root), or return `undefined` when there is none. This is the run-wide config carrying `baseUrl`/`webServer`; the CLI reads it to resolve options and manage the app-under-test lifecycle before calling [runEvalsInDir](Function.runEvalsInDir.md). |
 | [matches](Function.matches.md) | Passes when the value matches `pattern`. |
 | [mcpServer](Function.mcpServer.md) | Factory for declaring a custom MCP server tool. |
 | [normalizeHost](Function.normalizeHost.md) | Ensure the host has a scheme (Databricks env often lacks `https://`). |
 | [parseTextToolCalls](Function.parseTextToolCalls.md) | Parses text-based tool calls from model output. |
+| [readEvalDataset](Function.readEvalDataset.md) | Read a Databricks managed evaluation dataset (a Unity Catalog table with `inputs`/`expectations` columns) into rows, over the public SQL Statement Execution API. Reuses SQLWarehouseConnector for submit/poll/transform — its result transform already JSON-parses string columns into objects, so `inputs`/`expectations` come back as records whether the table stores them as JSON strings or structs. |
 | [reportToMlflow](Function.reportToMlflow.md) | Write one pass/fail assessment per eval result to the Databricks MLflow REST API. Never throws — failures are collected so the run still reports. |
-| [resolveDatabricksAuth](Function.resolveDatabricksAuth.md) | - |
+| [resolveDatabricksAuth](Function.resolveDatabricksAuth.md) | Resolve `{host, token}` for the eval runner the same way the rest of AppKit authenticates: construct a Databricks `WorkspaceClient` and let its config mint (and later refresh) an OAuth bearer from the CLI profile — no hand-set PAT required. An explicit host/token still wins (PAT or CI env), so the SDK is only consulted for whatever isn't supplied. |
 | [resolveHostedTools](Function.resolveHostedTools.md) | - |
+| [resolveWorkspaceClient](Function.resolveWorkspaceClient.md) | Construct a Databricks `WorkspaceClient` for the eval runner — the object the SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit host+token builds a PAT client; otherwise the profile (or ambient config) is used and the SDK resolves credentials, minting OAuth as needed. Returns `undefined` if construction throws (missing/invalid config). |
 | [runAgent](Function.runAgent.md) | Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion. |
+| [runBounded](Function.runBounded.md) | Run `tasks` through a bounded worker pool and return their results in the SAME order as the input, regardless of completion order. Each task receives its input index so callers can key on it. `limit` is clamped to at least 1 (and to the task count); at `limit === 1` this is a serial loop. Individual task rejections are surfaced per-slot via `settle` rather than aborting siblings — but eval tasks never reject (failures become results). |
 | [runEval](Function.runEval.md) | Run a single eval against a driver. Never throws for assertion or agent failures — those become a non-passing [EvalResult](Interface.EvalResult.md). Only a malformed eval definition surfaces as `result.error`. |
 | [runEvalsInDir](Function.runEvalsInDir.md) | Discover, load, and run every eval under each agent's `evals/` dir, driving the agents on a running app. Never throws for an individual eval — load/run failures become non-passing [EvalResult](Interface.EvalResult.md)s. |
+| [runWithRetries](Function.runWithRetries.md) | Run `attempt` up to `1 + retries` times, stopping as soon as it returns a result without an `error` (infra failures — thrown errors or timeouts — set `error`; assertion failures do not, so a failed-but-completed eval is returned on the first try and never retried). Returns the last result when every attempt errored. `retries` below 0 is treated as 0. |
 | [summarize](Function.summarize.md) | - |
-| [text](Function.text.md) | - |
-| [timestamp](Function.timestamp.md) | - |
 | [tool](Function.tool.md) | Factory for defining function tools with Zod schemas. |
 | [toolsFromRegistry](Function.toolsFromRegistry.md) | Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema. |
-| [uuid](Function.uuid.md) | - |
-| [varchar](Function.varchar.md) | - |
+| [userTurns](Function.userTurns.md) | Extract every user-message content, in order, from an MLflow `{"messages":[{"role":"user","content":"..."}]}` input. A dataset row can carry a full multi-turn conversation; replaying these against one thread (one `t.send` per returned string) lets the agent see the accumulating history. |
diff --git a/docs/docs/api/appkit/typedoc-sidebar.ts b/docs/docs/api/appkit/typedoc-sidebar.ts
index 6dd11de11..9d93fbc69 100644
--- a/docs/docs/api/appkit/typedoc-sidebar.ts
+++ b/docs/docs/api/appkit/typedoc-sidebar.ts
@@ -86,11 +86,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Class.ServerError",
           label: "ServerError"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Class.SupervisorApiAdapter",
-          label: "SupervisorApiAdapter"
-        },
         {
           type: "doc",
           id: "api/appkit/Class.TunnelError",
@@ -179,19 +174,24 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Interface.DatabaseRegistry",
-          label: "DatabaseRegistry"
+          id: "api/appkit/Interface.DatabricksAuth",
+          label: "DatabricksAuth"
         },
         {
           type: "doc",
-          id: "api/appkit/Interface.DatabricksAuth",
-          label: "DatabricksAuth"
+          id: "api/appkit/Interface.DatasetRow",
+          label: "DatasetRow"
         },
         {
           type: "doc",
           id: "api/appkit/Interface.DiscoveredEval",
           label: "DiscoveredEval"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.DiscoveredEvalConfig",
+          label: "DiscoveredEvalConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.DriveResult",
@@ -202,6 +202,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.EndpointConfig",
           label: "EndpointConfig"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.EvalConfig",
+          label: "EvalConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.EvalDefinition",
@@ -227,6 +232,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.EvalSummary",
           label: "EvalSummary"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.EvalWebServer",
+          label: "EvalWebServer"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.FilePolicyUser",
@@ -247,36 +257,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.GenerateDatabaseCredentialRequest",
           label: "GenerateDatabaseCredentialRequest"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.GenerationParams",
-          label: "GenerationParams"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.HostedSupervisorTool",
-          label: "HostedSupervisorTool"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.HttpDriverOptions",
           label: "HttpDriverOptions"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.IAiSearchConfig",
-          label: "IAiSearchConfig"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.IJobsConfig",
           label: "IJobsConfig"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.IndexConfig",
-          label: "IndexConfig"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.ITelemetry",
@@ -357,6 +347,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.PromptContext",
           label: "PromptContext"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.ReadEvalDatasetOptions",
+          label: "ReadEvalDatasetOptions"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.RegisteredAgent",
@@ -377,11 +372,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.RequestedResource",
           label: "RequestedResource"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.RerankerConfig",
-          label: "RerankerConfig"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.ResolveDatabricksAuthOptions",
@@ -417,26 +407,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.RunEvalsOptions",
           label: "RunEvalsOptions"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.Schema",
-          label: "Schema"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.SearchRequest",
-          label: "SearchRequest"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.SearchResponse",
-          label: "SearchResponse"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.SearchResult",
-          label: "SearchResult"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.ServingEndpointEntry",
@@ -452,16 +422,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.StreamExecutionSettings",
           label: "StreamExecutionSettings"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.SupervisorApiAdapterOptions",
-          label: "SupervisorApiAdapterOptions"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.SupervisorExtension",
-          label: "SupervisorExtension"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.TelemetryConfig",
@@ -516,21 +476,6 @@ const typedocSidebar: SidebarsConfig = {
           type: "doc",
           id: "api/appkit/Interface.ValidationResult",
           label: "ValidationResult"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.WorkspaceClient",
-          label: "WorkspaceClient"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.WorkspaceClientLike",
-          label: "WorkspaceClientLike"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.WorkspaceClientOptions",
-          label: "WorkspaceClientOptions"
         }
       ]
     },
@@ -568,11 +513,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.ConfigSchema",
           label: "ConfigSchema"
         },
-        {
-          type: "doc",
-          id: "api/appkit/TypeAlias.DatabaseExports",
-          label: "DatabaseExports"
-        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.EvalProgress",
@@ -605,8 +545,8 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/TypeAlias.IDatabaseConfig",
-          label: "IDatabaseConfig"
+          id: "api/appkit/TypeAlias.JobHandle",
+          label: "JobHandle"
         },
         {
           type: "doc",
@@ -643,11 +583,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.ResourcePermission",
           label: "ResourcePermission"
         },
-        {
-          type: "doc",
-          id: "api/appkit/TypeAlias.SearchFilters",
-          label: "SearchFilters"
-        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ServingFactory",
@@ -658,11 +593,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.Severity",
           label: "Severity"
         },
-        {
-          type: "doc",
-          id: "api/appkit/TypeAlias.SupervisorTool",
-          label: "SupervisorTool"
-        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ToolRegistry",
@@ -684,11 +614,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Variable.agents",
           label: "agents"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Variable.aiSearch",
-          label: "aiSearch"
-        },
         {
           type: "doc",
           id: "api/appkit/Variable.READ_ACTIONS",
@@ -699,16 +624,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Variable.sql",
           label: "sql"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Variable.SUPERVISOR_EXTENSION_KEY",
-          label: "SUPERVISOR_EXTENSION_KEY"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Variable.supervisorTools",
-          label: "supervisorTools"
-        },
         {
           type: "doc",
           id: "api/appkit/Variable.WRITE_ACTIONS",
@@ -735,21 +650,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.appKitTypesPlugin",
           label: "appKitTypesPlugin"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.bigid",
-          label: "bigid"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Function.bigint",
-          label: "bigint"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Function.boolean",
-          label: "boolean"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.buildAssessments",
@@ -785,16 +685,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.createLakebasePoolManager",
           label: "createLakebasePoolManager"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.createWorkspaceClient",
-          label: "createWorkspaceClient"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Function.database",
-          label: "database"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.defineEval",
@@ -802,13 +692,8 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Function.defineManifest",
-          label: "defineManifest"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Function.defineSchema",
-          label: "defineSchema"
+          id: "api/appkit/Function.defineEvalConfig",
+          label: "defineEvalConfig"
         },
         {
           type: "doc",
@@ -817,13 +702,13 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Function.discoverEvalFiles",
-          label: "discoverEvalFiles"
+          id: "api/appkit/Function.discoverEvalConfigs",
+          label: "discoverEvalConfigs"
         },
         {
           type: "doc",
-          id: "api/appkit/Function.enumColumn",
-          label: "enumColumn"
+          id: "api/appkit/Function.discoverEvalFiles",
+          label: "discoverEvalFiles"
         },
         {
           type: "doc",
@@ -847,13 +732,13 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Function.findServerFile",
-          label: "findServerFile"
+          id: "api/appkit/Function.findRootEvalConfig",
+          label: "findRootEvalConfig"
         },
         {
           type: "doc",
-          id: "api/appkit/Function.fk",
-          label: "fk"
+          id: "api/appkit/Function.findServerFile",
+          label: "findServerFile"
         },
         {
           type: "doc",
@@ -872,13 +757,18 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Function.formatSummaryLine",
-          label: "formatSummaryLine"
+          id: "api/appkit/Function.formatResultsJson",
+          label: "formatResultsJson"
         },
         {
           type: "doc",
-          id: "api/appkit/Function.fromSupervisorApi",
-          label: "fromSupervisorApi"
+          id: "api/appkit/Function.formatResultsJUnit",
+          label: "formatResultsJUnit"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.formatSummaryLine",
+          label: "formatSummaryLine"
         },
         {
           type: "doc",
@@ -925,21 +815,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.getWorkspaceClient",
           label: "getWorkspaceClient"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.id",
-          label: "id"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.includes",
           label: "includes"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.integer",
-          label: "integer"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.isFunctionTool",
@@ -960,21 +840,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.isSQLTypeMarker",
           label: "isSQLTypeMarker"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.isSupervisorTool",
-          label: "isSupervisorTool"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.isToolkitEntry",
           label: "isToolkitEntry"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.jsonb",
-          label: "jsonb"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.loadAgentFromFile",
@@ -985,6 +855,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.loadAgentsFromDir",
           label: "loadAgentsFromDir"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.loadRootEvalConfig",
+          label: "loadRootEvalConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.matches",
@@ -1005,6 +880,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.parseTextToolCalls",
           label: "parseTextToolCalls"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.readEvalDataset",
+          label: "readEvalDataset"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.reportToMlflow",
@@ -1020,11 +900,21 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.resolveHostedTools",
           label: "resolveHostedTools"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.resolveWorkspaceClient",
+          label: "resolveWorkspaceClient"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.runAgent",
           label: "runAgent"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.runBounded",
+          label: "runBounded"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.runEval",
@@ -1037,18 +927,13 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Function.summarize",
-          label: "summarize"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Function.text",
-          label: "text"
+          id: "api/appkit/Function.runWithRetries",
+          label: "runWithRetries"
         },
         {
           type: "doc",
-          id: "api/appkit/Function.timestamp",
-          label: "timestamp"
+          id: "api/appkit/Function.summarize",
+          label: "summarize"
         },
         {
           type: "doc",
@@ -1062,13 +947,8 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/Function.uuid",
-          label: "uuid"
-        },
-        {
-          type: "doc",
-          id: "api/appkit/Function.varchar",
-          label: "varchar"
+          id: "api/appkit/Function.userTurns",
+          label: "userTurns"
         }
       ]
     }

From ff62f394a0dd8b371b3b68d7ff57722b891b58a9 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Tue, 1 Sep 2026 18:30:00 +0200
Subject: [PATCH 3/4] fix(appkit): findRootEvalConfig uses existsSync;
 server/agents eval fixtures

findRootEvalConfig referenced an isFile helper that the eval-discovery refactor
had dropped; use existsSync (as discoverEvalConfigs does). Also align the config
discovery test fixtures to the server/agents layout the runner now uses.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 packages/appkit/src/evals/discover.ts            | 2 +-
 packages/appkit/src/evals/tests/discover.test.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/appkit/src/evals/discover.ts b/packages/appkit/src/evals/discover.ts
index e009ec362..dd0d1cec1 100644
--- a/packages/appkit/src/evals/discover.ts
+++ b/packages/appkit/src/evals/discover.ts
@@ -84,7 +84,7 @@ export function discoverEvalFiles(rootDir: string): DiscoveredEval[] {
  */
 export function findRootEvalConfig(rootDir: string): string | undefined {
   const file = path.join(rootDir, "evals.config.ts");
-  return isFile(file) ? file : undefined;
+  return existsSync(file) ? file : undefined;
 }
 
 /**
diff --git a/packages/appkit/src/evals/tests/discover.test.ts b/packages/appkit/src/evals/tests/discover.test.ts
index 67afc9cc1..4d51762a0 100644
--- a/packages/appkit/src/evals/tests/discover.test.ts
+++ b/packages/appkit/src/evals/tests/discover.test.ts
@@ -73,7 +73,7 @@ describe("findRootEvalConfig", () => {
   });
 
   test("returns undefined when absent (and ignores per-agent configs)", () => {
-    write("config/agents/support/evals/evals.config.ts");
+    write("server/agents/support/evals/evals.config.ts");
     expect(findRootEvalConfig(root)).toBeUndefined();
   });
 });

From ae370bfd037d58a44789d249c6f96a81321d90d4 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Thu, 3 Sep 2026 18:22:38 +0200
Subject: [PATCH 4/4] docs(appkit): regenerate api reference for eval framework

Regenerate the committed typedoc api docs against the rebased tree so the
sidebar matches the generated pages (adds Function.defineEvalConfig, drops
removed symbols like runBounded), fixing the docs build.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 .../api/appkit/Function.defineEvalConfig.md   |  17 ++
 .../appkit/Function.discoverEvalConfigs.md    |   2 +-
 .../api/appkit/Function.loadRootEvalConfig.md |   2 +-
 .../api/appkit/Function.readEvalDataset.md    |   2 +-
 .../appkit/Function.resolveWorkspaceClient.md |   2 +-
 docs/docs/api/appkit/Function.runBounded.md   |  34 ---
 .../appkit/Interface.AgentsPluginConfig.md    |  17 ++
 .../api/appkit/Interface.BasePluginConfig.md  |  13 ++
 .../appkit/Interface.DiscoveredEvalConfig.md  |   2 +-
 docs/docs/api/appkit/Interface.EvalConfig.md  |  67 ------
 .../api/appkit/Interface.EvalDefinition.md    |  21 ++
 .../api/appkit/Interface.IAiSearchConfig.md   |  17 ++
 docs/docs/api/appkit/Interface.IJobsConfig.md |  17 ++
 .../api/appkit/Interface.RunEvalsOptions.md   |  32 +--
 docs/docs/api/appkit/index.md                 |  64 ++++--
 docs/docs/api/appkit/typedoc-sidebar.ts       | 214 +++++++++++++++++-
 16 files changed, 377 insertions(+), 146 deletions(-)
 create mode 100644 docs/docs/api/appkit/Function.defineEvalConfig.md
 delete mode 100644 docs/docs/api/appkit/Function.runBounded.md
 delete mode 100644 docs/docs/api/appkit/Interface.EvalConfig.md

diff --git a/docs/docs/api/appkit/Function.defineEvalConfig.md b/docs/docs/api/appkit/Function.defineEvalConfig.md
new file mode 100644
index 000000000..72de6c6e0
--- /dev/null
+++ b/docs/docs/api/appkit/Function.defineEvalConfig.md
@@ -0,0 +1,17 @@
+# Function: defineEvalConfig()
+
+```ts
+function defineEvalConfig(config: EvalConfig): EvalConfig;
+```
+
+Define per-directory eval config. Default-export from `evals.config.ts`.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `config` | `EvalConfig` |
+
+## Returns
+
+`EvalConfig`
diff --git a/docs/docs/api/appkit/Function.discoverEvalConfigs.md b/docs/docs/api/appkit/Function.discoverEvalConfigs.md
index f350af5e0..14fc5500a 100644
--- a/docs/docs/api/appkit/Function.discoverEvalConfigs.md
+++ b/docs/docs/api/appkit/Function.discoverEvalConfigs.md
@@ -5,7 +5,7 @@ function discoverEvalConfigs(rootDir: string): DiscoveredEvalConfig[];
 ```
 
 Discover the per-agent `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at
-`<rootDir>/config/agents/<agent>/evals/evals.config.ts`. Config is per-agent:
+`<rootDir>/server/agents/<agent>/evals/evals.config.ts`. Config is per-agent:
 each agent's config applies only to that agent's evals. Agents without a
 config file are omitted. Returns a stable, sorted list.
 
diff --git a/docs/docs/api/appkit/Function.loadRootEvalConfig.md b/docs/docs/api/appkit/Function.loadRootEvalConfig.md
index b3238a821..8c505b1be 100644
--- a/docs/docs/api/appkit/Function.loadRootEvalConfig.md
+++ b/docs/docs/api/appkit/Function.loadRootEvalConfig.md
@@ -17,4 +17,4 @@ app-under-test lifecycle before calling [runEvalsInDir](Function.runEvalsInDir.m
 
 ## Returns
 
-`Promise`\<[`EvalConfig`](Interface.EvalConfig.md) \| `undefined`\>
+`Promise`\<`EvalConfig` \| `undefined`\>
diff --git a/docs/docs/api/appkit/Function.readEvalDataset.md b/docs/docs/api/appkit/Function.readEvalDataset.md
index 5ca486b2b..faf01d49f 100644
--- a/docs/docs/api/appkit/Function.readEvalDataset.md
+++ b/docs/docs/api/appkit/Function.readEvalDataset.md
@@ -18,7 +18,7 @@ equivalent), so we read the backing table directly.
 
 | Parameter | Type |
 | ------ | ------ |
-| `client` | `WorkspaceClient` |
+| `client` | [`WorkspaceClient`](Interface.WorkspaceClient.md) |
 | `options` | [`ReadEvalDatasetOptions`](Interface.ReadEvalDatasetOptions.md) |
 
 ## Returns
diff --git a/docs/docs/api/appkit/Function.resolveWorkspaceClient.md b/docs/docs/api/appkit/Function.resolveWorkspaceClient.md
index 1b80639b9..49d9fe00b 100644
--- a/docs/docs/api/appkit/Function.resolveWorkspaceClient.md
+++ b/docs/docs/api/appkit/Function.resolveWorkspaceClient.md
@@ -18,4 +18,4 @@ used and the SDK resolves credentials, minting OAuth as needed. Returns
 
 ## Returns
 
-`WorkspaceClient` \| `undefined`
+[`WorkspaceClient`](Interface.WorkspaceClient.md) \| `undefined`
diff --git a/docs/docs/api/appkit/Function.runBounded.md b/docs/docs/api/appkit/Function.runBounded.md
deleted file mode 100644
index 1a08b36bf..000000000
--- a/docs/docs/api/appkit/Function.runBounded.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Function: runBounded()
-
-```ts
-function runBounded<T, R>(
-   tasks: readonly T[], 
-   limit: number, 
-worker: (task: T, index: number) => Promise<R>): Promise<R[]>;
-```
-
-Run `tasks` through a bounded worker pool and return their results in the
-SAME order as the input, regardless of completion order. Each task receives
-its input index so callers can key on it. `limit` is clamped to at least 1
-(and to the task count); at `limit === 1` this is a serial loop. Individual
-task rejections are surfaced per-slot via `settle` rather than aborting
-siblings — but eval tasks never reject (failures become results).
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-| `R` |
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `tasks` | readonly `T`[] |
-| `limit` | `number` |
-| `worker` | (`task`: `T`, `index`: `number`) => `Promise`\<`R`\> |
-
-## Returns
-
-`Promise`\<`R`[]\>
diff --git a/docs/docs/api/appkit/Interface.AgentsPluginConfig.md b/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
index a2f2c963f..2f888b9d0 100644
--- a/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
+++ b/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
@@ -260,6 +260,23 @@ are discovered at boot and on `reload()` and read as the service principal.
 
 ***
 
+### streamConfig?
+
+```ts
+optional streamConfig: StreamConfig;
+```
+
+SSE stream configuration for this plugin's `executeStream()` calls (buffer
+sizes, `maxEventSize`, TTL, heartbeat). Sets the plugin's StreamManager
+defaults; a per-call `stream` config still overrides these. Use it to raise
+`maxEventSize` above the 5 MiB default when a stream emits larger events.
+
+#### Inherited from
+
+[`BasePluginConfig`](Interface.BasePluginConfig.md).[`streamConfig`](Interface.BasePluginConfig.md#streamconfig)
+
+***
+
 ### telemetry?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.BasePluginConfig.md b/docs/docs/api/appkit/Interface.BasePluginConfig.md
index a109fd560..9ee98474b 100644
--- a/docs/docs/api/appkit/Interface.BasePluginConfig.md
+++ b/docs/docs/api/appkit/Interface.BasePluginConfig.md
@@ -32,6 +32,19 @@ optional name: string;
 
 ***
 
+### streamConfig?
+
+```ts
+optional streamConfig: StreamConfig;
+```
+
+SSE stream configuration for this plugin's `executeStream()` calls (buffer
+sizes, `maxEventSize`, TTL, heartbeat). Sets the plugin's StreamManager
+defaults; a per-call `stream` config still overrides these. Use it to raise
+`maxEventSize` above the 5 MiB default when a stream emits larger events.
+
+***
+
 ### telemetry?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md b/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md
index 7b4f2a831..0f75d6015 100644
--- a/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md
+++ b/docs/docs/api/appkit/Interface.DiscoveredEvalConfig.md
@@ -1,6 +1,6 @@
 # Interface: DiscoveredEvalConfig
 
-A per-agent `evals.config.ts` found under `config/agents/<agent>/evals/`.
+A per-agent `evals.config.ts` found under `server/agents/<agent>/evals/`.
 
 ## Properties
 
diff --git a/docs/docs/api/appkit/Interface.EvalConfig.md b/docs/docs/api/appkit/Interface.EvalConfig.md
deleted file mode 100644
index 4d8fd8519..000000000
--- a/docs/docs/api/appkit/Interface.EvalConfig.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Interface: EvalConfig
-
-Eval config from `evals.config.ts` (via [defineEvalConfig](Function.defineEvalConfig.md)).
-
-Two scopes share this shape: a **root** `evals.config.ts` (project root) may
-set run-wide settings — `baseUrl` and `webServer` — plus defaults for
-`maxConcurrency`/`timeoutMs`; a **per-agent** `config/agents/<id>/evals/evals.config.ts`
-sets only that agent's `maxConcurrency`/`timeoutMs` overrides (`baseUrl`/
-`webServer` there are ignored — server lifecycle is run-wide).
-
-## Properties
-
-### baseUrl?
-
-```ts
-optional baseUrl: string;
-```
-
-Base URL of the app to drive (root config only). Overridden by `--url`.
-
-***
-
-### judge?
-
-```ts
-optional judge: {
-  model?: string;
-};
-```
-
-LLM judge config. Defaults to the agent's own serving endpoint.
-
-#### model?
-
-```ts
-optional model: string;
-```
-
-***
-
-### maxConcurrency?
-
-```ts
-optional maxConcurrency: number;
-```
-
-Max evals to run concurrently.
-
-***
-
-### timeoutMs?
-
-```ts
-optional timeoutMs: number;
-```
-
-Default per-eval timeout.
-
-***
-
-### webServer?
-
-```ts
-optional webServer: EvalWebServer;
-```
-
-Auto-start the app under test (root config only).
diff --git a/docs/docs/api/appkit/Interface.EvalDefinition.md b/docs/docs/api/appkit/Interface.EvalDefinition.md
index cea1d47e7..cdaa2ea5e 100644
--- a/docs/docs/api/appkit/Interface.EvalDefinition.md
+++ b/docs/docs/api/appkit/Interface.EvalDefinition.md
@@ -50,6 +50,27 @@ optional description: string;
 
 Short human description, shown in reports.
 
+***
+
+### tags?
+
+```ts
+optional tags: string[];
+```
+
+Free-form tags for filtering (see the runner's `tags` / `--tag` option).
+
+***
+
+### timeoutMs?
+
+```ts
+optional timeoutMs: number;
+```
+
+Per-eval timeout (ms): `runEval` races the test against it and records a
+non-passing result instead of hanging. Overrides the runner/CLI default.
+
 ## Methods
 
 ### test()
diff --git a/docs/docs/api/appkit/Interface.IAiSearchConfig.md b/docs/docs/api/appkit/Interface.IAiSearchConfig.md
index 316b4aac3..679d8b18f 100644
--- a/docs/docs/api/appkit/Interface.IAiSearchConfig.md
+++ b/docs/docs/api/appkit/Interface.IAiSearchConfig.md
@@ -46,6 +46,23 @@ optional name: string;
 
 ***
 
+### streamConfig?
+
+```ts
+optional streamConfig: StreamConfig;
+```
+
+SSE stream configuration for this plugin's `executeStream()` calls (buffer
+sizes, `maxEventSize`, TTL, heartbeat). Sets the plugin's StreamManager
+defaults; a per-call `stream` config still overrides these. Use it to raise
+`maxEventSize` above the 5 MiB default when a stream emits larger events.
+
+#### Inherited from
+
+[`BasePluginConfig`](Interface.BasePluginConfig.md).[`streamConfig`](Interface.BasePluginConfig.md#streamconfig)
+
+***
+
 ### telemetry?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.IJobsConfig.md b/docs/docs/api/appkit/Interface.IJobsConfig.md
index aeff8fa92..d86e7280c 100644
--- a/docs/docs/api/appkit/Interface.IJobsConfig.md
+++ b/docs/docs/api/appkit/Interface.IJobsConfig.md
@@ -58,6 +58,23 @@ Poll interval for waitForRun in milliseconds. Defaults to 5000.
 
 ***
 
+### streamConfig?
+
+```ts
+optional streamConfig: StreamConfig;
+```
+
+SSE stream configuration for this plugin's `executeStream()` calls (buffer
+sizes, `maxEventSize`, TTL, heartbeat). Sets the plugin's StreamManager
+defaults; a per-call `stream` config still overrides these. Use it to raise
+`maxEventSize` above the 5 MiB default when a stream emits larger events.
+
+#### Inherited from
+
+[`BasePluginConfig`](Interface.BasePluginConfig.md).[`streamConfig`](Interface.BasePluginConfig.md#streamconfig)
+
+***
+
 ### telemetry?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.RunEvalsOptions.md b/docs/docs/api/appkit/Interface.RunEvalsOptions.md
index c1c7ec78a..38db8f471 100644
--- a/docs/docs/api/appkit/Interface.RunEvalsOptions.md
+++ b/docs/docs/api/appkit/Interface.RunEvalsOptions.md
@@ -12,6 +12,19 @@ Base URL of the running app to drive, e.g. `http://localhost:3000`.
 
 ***
 
+### concurrency?
+
+```ts
+optional concurrency: number;
+```
+
+Max evals to drive concurrently. Each eval opens one stream to the app as
+the same user, so keep this at or below the app's
+`maxConcurrentStreamsPerUser` (default 5) or the surplus streams hit the
+429 guard. Defaults to 4; clamped to `[1, total]`.
+
+***
+
 ### filter?
 
 ```ts
@@ -65,18 +78,6 @@ token: string;
 
 ***
 
-### maxConcurrency?
-
-```ts
-optional maxConcurrency: number;
-```
-
-Max evals/dataset rows to drive concurrently. Defaults to `1` (serial).
-Values below 1 are clamped to 1. Output order is preserved regardless.
-Wins over an agent's `evals.config.ts` `maxConcurrency`.
-
-***
-
 ### mlflow?
 
 ```ts
@@ -169,7 +170,7 @@ retried (a wrong reply is real signal, not flake). Defaults to `0`.
 optional rootDir: string;
 ```
 
-Project root containing `config/agents/`. Defaults to `process.cwd()`.
+Project root containing `server/agents/`. Defaults to `process.cwd()`.
 
 ***
 
@@ -200,8 +201,9 @@ Tags live on the eval def, so filtering happens after each file is loaded.
 optional timeoutMs: number;
 ```
 
-Default per-eval timeout (ms). A per-eval `def.timeoutMs` overrides it.
-Wins over an agent's `evals.config.ts` `timeoutMs`.
+Default per-eval timeout (ms): `runEval` races the whole test against it and
+it also caps each driver turn. A per-eval `def.timeoutMs` overrides it, and
+it wins over an agent's `evals.config.ts` `timeoutMs`. Unbounded when unset.
 
 ***
 
diff --git a/docs/docs/api/appkit/index.md b/docs/docs/api/appkit/index.md
index c3fc41620..081dfef4c 100644
--- a/docs/docs/api/appkit/index.md
+++ b/docs/docs/api/appkit/index.md
@@ -27,6 +27,7 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [PolicyDeniedError](Class.PolicyDeniedError.md) | Thrown when a policy denies an action. |
 | [ResourceRegistry](Class.ResourceRegistry.md) | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only. |
 | [ServerError](Class.ServerError.md) | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc. |
+| [SupervisorApiAdapter](Class.SupervisorApiAdapter.md) | Adapter that calls the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`). |
 | [TunnelError](Class.TunnelError.md) | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc. |
 | [ValidationError](Class.ValidationError.md) | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches. |
 
@@ -48,13 +49,13 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [CacheConfig](Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
 | [CustomJudgeSpec](Interface.CustomJudgeSpec.md) | A custom LLM-judge definition: a prompt template and choice→score mapping. |
 | [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
+| [DatabaseRegistry](Interface.DatabaseRegistry.md) | CANONICAL augmentation target. Empty by default; the generated `database.d.ts` augments it via `declare module "@databricks/appkit" { interface DatabaseRegistry { ... } }`. |
 | [DatabricksAuth](Interface.DatabricksAuth.md) | Resolved Databricks host + bearer token for the eval runner's REST calls. |
 | [DatasetRow](Interface.DatasetRow.md) | One row of a managed evaluation dataset. `inputs` are the kwargs passed to the agent for the turn; `expectations` (when present) is the row's ground truth / guidelines. Mirrors the `{inputs, expectations}` shape of `mlflow.genai` datasets and of the Unity Catalog table backing a managed eval dataset. |
-| [DiscoveredEval](Interface.DiscoveredEval.md) | An eval file found under `config/agents/<agent>/evals/`. |
-| [DiscoveredEvalConfig](Interface.DiscoveredEvalConfig.md) | A per-agent `evals.config.ts` found under `config/agents/<agent>/evals/`. |
+| [DiscoveredEval](Interface.DiscoveredEval.md) | An eval file found under `server/agents/<agent>/evals/`. |
+| [DiscoveredEvalConfig](Interface.DiscoveredEvalConfig.md) | A per-agent `evals.config.ts` found under `server/agents/<agent>/evals/`. |
 | [DriveResult](Interface.DriveResult.md) | What a driver returns for a single `t.send`. |
 | [EndpointConfig](Interface.EndpointConfig.md) | - |
-| [EvalConfig](Interface.EvalConfig.md) | Eval config from `evals.config.ts` (via [defineEvalConfig](Function.defineEvalConfig.md)). |
 | [EvalDefinition](Interface.EvalDefinition.md) | A single eval, default-exported from a `*.eval.ts` file. |
 | [EvalDriver](Interface.EvalDriver.md) | Abstraction over how the agent is driven. The HTTP driver posts to a running app's agents endpoint; future drivers (in-process) implement the same shape. |
 | [EvalResult](Interface.EvalResult.md) | The outcome of running one eval. |
@@ -65,8 +66,12 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [FileResource](Interface.FileResource.md) | Describes the file or directory being acted upon. |
 | [FunctionTool](Interface.FunctionTool.md) | - |
 | [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
+| [GenerationParams](Interface.GenerationParams.md) | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates. |
+| [HostedSupervisorTool](Interface.HostedSupervisorTool.md) | Tagged record returned by every [supervisorTools](Variable.supervisorTools.md) factory. The `__kind` discriminator lets the agents plugin (and standalone `runAgent`) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use `type: "genie-space"` hyphenated, vs SA's `type: "genie_space"` underscored). |
 | [HttpDriverOptions](Interface.HttpDriverOptions.md) | - |
+| [IAiSearchConfig](Interface.IAiSearchConfig.md) | Base configuration interface for AppKit plugins |
 | [IJobsConfig](Interface.IJobsConfig.md) | Configuration for the Jobs plugin. |
+| [IndexConfig](Interface.IndexConfig.md) | - |
 | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
 | [JobAPI](Interface.JobAPI.md) | User-facing API for a single configured job. |
 | [JobConfig](Interface.JobConfig.md) | Per-job configuration options. |
@@ -88,6 +93,7 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [ReportOutcome](Interface.ReportOutcome.md) | - |
 | [RequestedClaims](Interface.RequestedClaims.md) | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables |
 | [RequestedResource](Interface.RequestedResource.md) | Resource to request permissions for in Unity Catalog |
+| [RerankerConfig](Interface.RerankerConfig.md) | - |
 | [ResolveDatabricksAuthOptions](Interface.ResolveDatabricksAuthOptions.md) | - |
 | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
 | [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). |
@@ -95,9 +101,15 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [RunAgentResult](Interface.RunAgentResult.md) | - |
 | [RunEvalOptions](Interface.RunEvalOptions.md) | - |
 | [RunEvalsOptions](Interface.RunEvalsOptions.md) | - |
+| [Schema](Interface.Schema.md) | One finalized schema. `TTableName` keeps the declared names in the type, so configuration that addresses a table by name is checked against the schema it was written for. Code that accepts any schema uses the default. |
+| [SearchRequest](Interface.SearchRequest.md) | - |
+| [SearchResponse](Interface.SearchResponse.md) | - |
+| [SearchResult](Interface.SearchResult.md) | - |
 | [ServingEndpointEntry](Interface.ServingEndpointEntry.md) | Shape of a single registry entry. |
 | [ServingEndpointRegistry](Interface.ServingEndpointRegistry.md) | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint. |
 | [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. |
+| [SupervisorApiAdapterOptions](Interface.SupervisorApiAdapterOptions.md) | - |
+| [SupervisorExtension](Interface.SupervisorExtension.md) | Shape of the value at `AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]`. The agents plugin / `runAgent` build this from the tool index; advanced callers invoking `adapter.run(...)` directly populate it themselves. |
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
 | [TestContext](Interface.TestContext.md) | The `t` context passed to an eval's `test` function. |
 | [Thread](Interface.Thread.md) | - |
@@ -109,24 +121,28 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [ToolkitOptions](Interface.ToolkitOptions.md) | - |
 | [ToolProvider](Interface.ToolProvider.md) | - |
 | [ValidationResult](Interface.ValidationResult.md) | Result of validating all registered resources against the environment. |
+| [WorkspaceClient](Interface.WorkspaceClient.md) | AppKit's workspace client facade. Mirrors the multi-client shape of the modular Databricks SDK: each service is its own accessor, so services can be migrated one at a time behind this stable interface. |
+| [WorkspaceClientLike](Interface.WorkspaceClientLike.md) | Structural shape of a Databricks SDK client used by [fromSupervisorApi](Function.fromSupervisorApi.md). Only what we need: `apiClient.request` for streaming and `config.ensureResolved` to materialise the host/credentials. |
+| [WorkspaceClientOptions](Interface.WorkspaceClientOptions.md) | Options used to construct the wrapper. Mirrors the subset of the old SDK's `Config` + `ClientOptions` that AppKit relies on today; we deliberately do NOT re-expose every old-SDK config knob. |
 
 ## Type Aliases
 
 | Type Alias | Description |
 | ------ | ------ |
 | [AgentEvent](TypeAlias.AgentEvent.md) | - |
-| [AgentTool](TypeAlias.AgentTool.md) | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), or toolkit references from plugins (`analytics().toolkit()`). |
+| [AgentTool](TypeAlias.AgentTool.md) | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), toolkit references from plugins (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools (`supervisorTools.*`). |
 | [AgentTools](TypeAlias.AgentTools.md) | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc. |
 | [AgentToolsFn](TypeAlias.AgentToolsFn.md) | Function form of `AgentDefinition.tools`. Receives the typed [Plugins](TypeAlias.Plugins.md) map and returns a tool record. Invoked exactly once at setup (or once per `runAgent` call in standalone mode); the result is cached as the agent's resolved tool record. |
 | [BaseSystemPromptOption](TypeAlias.BaseSystemPromptOption.md) | - |
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
+| [DatabaseExports](TypeAlias.DatabaseExports.md) | Typed database API published by the plugin. |
 | [EvalProgress](TypeAlias.EvalProgress.md) | - |
 | [ExecutionResult](TypeAlias.ExecutionResult.md) | Discriminated union for plugin execution results. |
 | [FileAction](TypeAlias.FileAction.md) | Every action the files plugin can perform. |
 | [FilePolicy](TypeAlias.FilePolicy.md) | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
 | [HostedTool](TypeAlias.HostedTool.md) | - |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
-| [JobHandle](TypeAlias.JobHandle.md) | Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`. |
+| [IDatabaseConfig](TypeAlias.IDatabaseConfig.md) | Configuration for one schema-bound DatabasePlugin instance. |
 | [JobsExport](TypeAlias.JobsExport.md) | Public API shape of the jobs plugin. Callable to select a job by key. |
 | [Matcher](TypeAlias.Matcher.md) | A deterministic matcher: inspects a string value and returns a result. |
 | [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
@@ -134,8 +150,10 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [ResolvedToolEntry](TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
 | [ResourceFieldEntry](TypeAlias.ResourceFieldEntry.md) | - |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
+| [SearchFilters](TypeAlias.SearchFilters.md) | - |
 | [ServingFactory](TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. |
 | [Severity](TypeAlias.Severity.md) | Whether an assertion fails the eval (`gate`) or is tracked only (`soft`). |
+| [SupervisorTool](TypeAlias.SupervisorTool.md) | Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body. |
 | [ToolRegistry](TypeAlias.ToolRegistry.md) | - |
 | [ToPlugin](TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
 
@@ -143,9 +161,12 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 
 | Variable | Description |
 | ------ | ------ |
-| [agents](Variable.agents.md) | Plugin factory for the agents plugin. Reads `config/agents/*.md` by default, resolves toolkits/tools from registered plugins, exposes `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
+| [agents](Variable.agents.md) | Plugin factory for the agents plugin. Discovers agents from `server/agents/<id>/agent.{ts,md}` by default (markdown still in `config/agents/` is read as a deprecated fallback), resolves toolkits/tools from registered plugins, exposes the `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
+| [aiSearch](Variable.aiSearch.md) | - |
 | [READ\_ACTIONS](Variable.READ_ACTIONS.md) | Actions that only read data. |
 | [sql](Variable.sql.md) | SQL helper namespace |
+| [SUPERVISOR\_EXTENSION\_KEY](Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads. |
+| [supervisorTools](Variable.supervisorTools.md) | Concise factories for declaring Supervisor API tools. |
 | [WRITE\_ACTIONS](Variable.WRITE_ACTIONS.md) | Actions that mutate data. |
 
 ## Functions
@@ -155,30 +176,40 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [agentIdFromMarkdownPath](Function.agentIdFromMarkdownPath.md) | Derives the logical agent id from a markdown path. When the file is named `agent.md`, the id is the parent directory name (folder-based layout); otherwise the id is the file stem (e.g. legacy single-file paths). |
 | [appKitServingTypesPlugin](Function.appKitServingTypesPlugin.md) | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation. |
 | [appKitTypesPlugin](Function.appKitTypesPlugin.md) | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood. |
-| [buildAssessments](Function.buildAssessments.md) | Build the Feedback assessments for an eval result: one per assertion (judge assertions tagged `LLM_JUDGE` with their numeric score + rationale, so they render as judge feedback in MLflow) plus an overall `appkit_eval` pass/fail. Returns [] when there's no trace to attach to or the eval was skipped. |
+| [bigid](Function.bigid.md) | - |
+| [bigint](Function.bigint.md) | - |
+| [boolean](Function.boolean.md) | - |
+| [buildAssessments](Function.buildAssessments.md) | - |
 | [configureJudge](Function.configureJudge.md) | Configure the judge once. Sets the OpenAI-compatible client env autoevals reads and the default judge model. No-op-safe: on failure, judging stays disabled and [isJudgeConfigured](Function.isJudgeConfigured.md) returns false. |
-| [createAgent](Function.createAgent.md) | Pure factory for agent definitions. Returns the passed-in definition after cycle-detecting the sub-agent graph. Accepts the full `AgentDefinition` shape and is safe to call at module top-level. |
+| [createAgent](Function.createAgent.md) | Pure factory for agent definitions: cycle-detects the sub-agent graph and returns the same object, stamped with a non-enumerable AGENT\_BRAND so discovery recognizes it. Safe at module top-level; no adapter is built. Don't `Object.freeze` the definition before passing it in — the brand is written onto the argument. |
 | [createApp](Function.createApp.md) | Bootstraps AppKit with the provided configuration. |
 | [createHttpDriver](Function.createHttpDriver.md) | Drives an agent by POSTing to a running app's chat endpoint and parsing the SSE response. Keeps the thread id across `send`s so multi-turn evals share a conversation. Agent/stream errors surface as `succeeded: false` rather than throwing, so `t.succeeded()` can assert on them. |
 | [createLakebasePool](Function.createLakebasePool.md) | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry. |
 | [createLakebasePoolManager](Function.createLakebasePoolManager.md) | Create a pool manager that maintains per-key Lakebase connection pools. |
-| [defineEval](Function.defineEval.md) | Define an agent eval. Default-export the result from a `config/agents/<id>/evals/*.eval.ts` file. |
+| [createWorkspaceClient](Function.createWorkspaceClient.md) | Construct an AppKit workspace client. |
+| [database](Function.database.md) | Create a typed database plugin registration for a finalized schema. |
+| [defineEval](Function.defineEval.md) | Define an agent eval. Default-export the result from a `server/agents/<id>/evals/*.eval.ts` file. |
 | [defineEvalConfig](Function.defineEvalConfig.md) | Define per-directory eval config. Default-export from `evals.config.ts`. |
+| [defineManifest](Function.defineManifest.md) | Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](Interface.PluginManifest.md). |
+| [defineSchema](Function.defineSchema.md) | Compile one declared schema. The returned type keeps the table names the builder returned, so `crudRoutes` and `hooks` can name only real tables. |
 | [defineTool](Function.defineTool.md) | Defines a single tool entry for a plugin's internal registry. |
-| [discoverEvalConfigs](Function.discoverEvalConfigs.md) | Discover the per-agent `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at `<rootDir>/config/agents/<agent>/evals/evals.config.ts`. Config is per-agent: each agent's config applies only to that agent's evals. Agents without a config file are omitted. Returns a stable, sorted list. |
-| [discoverEvalFiles](Function.discoverEvalFiles.md) | Discover evals under `<rootDir>/config/agents/<agent>/evals/`. The agent id is the directory name; the eval id is the file path relative to that evals dir with `.eval.ts` stripped. Returns a stable, sorted list. |
+| [discoverEvalConfigs](Function.discoverEvalConfigs.md) | Discover the per-agent `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at `<rootDir>/server/agents/<agent>/evals/evals.config.ts`. Config is per-agent: each agent's config applies only to that agent's evals. Agents without a config file are omitted. Returns a stable, sorted list. |
+| [discoverEvalFiles](Function.discoverEvalFiles.md) | Discover evals under `<rootDir>/server/agents/<agent>/evals/` — co-located with each agent's `agent.{md,ts}` (same folder-per-agent layout the agents plugin discovers). The agent id is the folder name; the eval id is the file path relative to that evals dir with `.eval.ts` stripped. Sorted + stable. |
+| [enumColumn](Function.enumColumn.md) | - |
 | [equals](Function.equals.md) | Passes when the value equals `expected` exactly. |
 | [evalGlyph](Function.evalGlyph.md) | Status glyph for a single eval result. |
 | [executeFromRegistry](Function.executeFromRegistry.md) | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn. |
 | [extractServingEndpoints](Function.extractServingEndpoints.md) | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings. |
 | [findRootEvalConfig](Function.findRootEvalConfig.md) | Path to the root `evals.config.ts` (from [defineEvalConfig](Function.defineEvalConfig.md)) at `<rootDir>/evals.config.ts`, or `undefined` when absent. The root config holds run-wide settings (`baseUrl`, `webServer`); it's distinct from the per-agent configs found by [discoverEvalConfigs](Function.discoverEvalConfigs.md). |
 | [findServerFile](Function.findServerFile.md) | Find the server entry file by checking candidate paths in order. |
+| [fk](Function.fk.md) | Declare foreign-key to another column. |
 | [formatEvalDetail](Function.formatEvalDetail.md) | Indented detail lines for a failing eval (error + failing assertions). |
 | [formatEvalHeadline](Function.formatEvalHeadline.md) | The one-line header for a single eval result (no failure detail). |
 | [formatEvalResults](Function.formatEvalResults.md) | Render all results as a human-readable console report (non-streaming). |
 | [formatResultsJson](Function.formatResultsJson.md) | Render results as a machine-readable JSON report (2-space indented): `{ summary: EvalSummary, results: EvalResult[] }`. Faithful to the types — every field present on a result round-trips. |
 | [formatResultsJUnit](Function.formatResultsJUnit.md) | Render results as JUnit XML for standard CI test reporters: a single `<testsuite name="appkit-agent-evals">` with one `<testcase>` per result. Failures carry a `<failure>` (error or failing-gate summary); skips a `<skipped>`. All attribute/text values are XML-escaped. |
 | [formatSummaryLine](Function.formatSummaryLine.md) | The final PASS/FAIL summary line. |
+| [fromSupervisorApi](Function.fromSupervisorApi.md) | Creates an [AgentAdapter](Interface.AgentAdapter.md) backed by the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`). |
 | [functionToolToDefinition](Function.functionToolToDefinition.md) | - |
 | [generateDatabaseCredential](Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API. |
 | [getExecutionContext](Function.getExecutionContext.md) | Get the current execution context. |
@@ -188,12 +219,16 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [getResourceRequirements](Function.getResourceRequirements.md) | Gets the resource requirements from a plugin's manifest. |
 | [getUsernameWithApiLookup](Function.getUsernameWithApiLookup.md) | Resolves the PostgreSQL username for a Lakebase connection. |
 | [getWorkspaceClient](Function.getWorkspaceClient.md) | Get workspace client from config or SDK default auth chain |
+| [id](Function.id.md) | - |
 | [includes](Function.includes.md) | Passes when the value contains `substring`. |
+| [integer](Function.integer.md) | - |
 | [isFunctionTool](Function.isFunctionTool.md) | - |
 | [isHostedTool](Function.isHostedTool.md) | - |
 | [isJudgeConfigured](Function.isJudgeConfigured.md) | - |
 | [isSQLTypeMarker](Function.isSQLTypeMarker.md) | Type guard to check if a value is a SQL type marker |
+| [isSupervisorTool](Function.isSupervisorTool.md) | Type guard for [HostedSupervisorTool](Interface.HostedSupervisorTool.md). Used by the agents plugin (`buildToolIndex`) and standalone `runAgent` (`classifyTool`) to route supervisor-hosted tools to the extensions payload rather than the adapter's `tools` array. |
 | [isToolkitEntry](Function.isToolkitEntry.md) | Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record. |
+| [jsonb](Function.jsonb.md) | - |
 | [loadAgentFromFile](Function.loadAgentFromFile.md) | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library. |
 | [loadAgentsFromDir](Function.loadAgentsFromDir.md) | Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist. |
 | [loadRootEvalConfig](Function.loadRootEvalConfig.md) | Load the root `evals.config.ts` under `rootDir` (the project root), or return `undefined` when there is none. This is the run-wide config carrying `baseUrl`/`webServer`; the CLI reads it to resolve options and manage the app-under-test lifecycle before calling [runEvalsInDir](Function.runEvalsInDir.md). |
@@ -203,15 +238,18 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | [parseTextToolCalls](Function.parseTextToolCalls.md) | Parses text-based tool calls from model output. |
 | [readEvalDataset](Function.readEvalDataset.md) | Read a Databricks managed evaluation dataset (a Unity Catalog table with `inputs`/`expectations` columns) into rows, over the public SQL Statement Execution API. Reuses SQLWarehouseConnector for submit/poll/transform — its result transform already JSON-parses string columns into objects, so `inputs`/`expectations` come back as records whether the table stores them as JSON strings or structs. |
 | [reportToMlflow](Function.reportToMlflow.md) | Write one pass/fail assessment per eval result to the Databricks MLflow REST API. Never throws — failures are collected so the run still reports. |
-| [resolveDatabricksAuth](Function.resolveDatabricksAuth.md) | Resolve `{host, token}` for the eval runner the same way the rest of AppKit authenticates: construct a Databricks `WorkspaceClient` and let its config mint (and later refresh) an OAuth bearer from the CLI profile — no hand-set PAT required. An explicit host/token still wins (PAT or CI env), so the SDK is only consulted for whatever isn't supplied. |
+| [resolveDatabricksAuth](Function.resolveDatabricksAuth.md) | - |
 | [resolveHostedTools](Function.resolveHostedTools.md) | - |
 | [resolveWorkspaceClient](Function.resolveWorkspaceClient.md) | Construct a Databricks `WorkspaceClient` for the eval runner — the object the SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit host+token builds a PAT client; otherwise the profile (or ambient config) is used and the SDK resolves credentials, minting OAuth as needed. Returns `undefined` if construction throws (missing/invalid config). |
 | [runAgent](Function.runAgent.md) | Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion. |
-| [runBounded](Function.runBounded.md) | Run `tasks` through a bounded worker pool and return their results in the SAME order as the input, regardless of completion order. Each task receives its input index so callers can key on it. `limit` is clamped to at least 1 (and to the task count); at `limit === 1` this is a serial loop. Individual task rejections are surfaced per-slot via `settle` rather than aborting siblings — but eval tasks never reject (failures become results). |
 | [runEval](Function.runEval.md) | Run a single eval against a driver. Never throws for assertion or agent failures — those become a non-passing [EvalResult](Interface.EvalResult.md). Only a malformed eval definition surfaces as `result.error`. |
 | [runEvalsInDir](Function.runEvalsInDir.md) | Discover, load, and run every eval under each agent's `evals/` dir, driving the agents on a running app. Never throws for an individual eval — load/run failures become non-passing [EvalResult](Interface.EvalResult.md)s. |
 | [runWithRetries](Function.runWithRetries.md) | Run `attempt` up to `1 + retries` times, stopping as soon as it returns a result without an `error` (infra failures — thrown errors or timeouts — set `error`; assertion failures do not, so a failed-but-completed eval is returned on the first try and never retried). Returns the last result when every attempt errored. `retries` below 0 is treated as 0. |
 | [summarize](Function.summarize.md) | - |
+| [text](Function.text.md) | - |
+| [timestamp](Function.timestamp.md) | - |
 | [tool](Function.tool.md) | Factory for defining function tools with Zod schemas. |
 | [toolsFromRegistry](Function.toolsFromRegistry.md) | Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema. |
 | [userTurns](Function.userTurns.md) | Extract every user-message content, in order, from an MLflow `{"messages":[{"role":"user","content":"..."}]}` input. A dataset row can carry a full multi-turn conversation; replaying these against one thread (one `t.send` per returned string) lets the agent see the accumulating history. |
+| [uuid](Function.uuid.md) | - |
+| [varchar](Function.varchar.md) | - |
diff --git a/docs/docs/api/appkit/typedoc-sidebar.ts b/docs/docs/api/appkit/typedoc-sidebar.ts
index 9d93fbc69..ba4fbf41b 100644
--- a/docs/docs/api/appkit/typedoc-sidebar.ts
+++ b/docs/docs/api/appkit/typedoc-sidebar.ts
@@ -86,6 +86,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Class.ServerError",
           label: "ServerError"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Class.SupervisorApiAdapter",
+          label: "SupervisorApiAdapter"
+        },
         {
           type: "doc",
           id: "api/appkit/Class.TunnelError",
@@ -172,6 +177,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.DatabaseCredential",
           label: "DatabaseCredential"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.DatabaseRegistry",
+          label: "DatabaseRegistry"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.DatabricksAuth",
@@ -202,11 +212,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.EndpointConfig",
           label: "EndpointConfig"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Interface.EvalConfig",
-          label: "EvalConfig"
-        },
         {
           type: "doc",
           id: "api/appkit/Interface.EvalDefinition",
@@ -257,16 +262,36 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.GenerateDatabaseCredentialRequest",
           label: "GenerateDatabaseCredentialRequest"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.GenerationParams",
+          label: "GenerationParams"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.HostedSupervisorTool",
+          label: "HostedSupervisorTool"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.HttpDriverOptions",
           label: "HttpDriverOptions"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.IAiSearchConfig",
+          label: "IAiSearchConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.IJobsConfig",
           label: "IJobsConfig"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.IndexConfig",
+          label: "IndexConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.ITelemetry",
@@ -372,6 +397,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.RequestedResource",
           label: "RequestedResource"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.RerankerConfig",
+          label: "RerankerConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.ResolveDatabricksAuthOptions",
@@ -407,6 +437,26 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.RunEvalsOptions",
           label: "RunEvalsOptions"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.Schema",
+          label: "Schema"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.SearchRequest",
+          label: "SearchRequest"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.SearchResponse",
+          label: "SearchResponse"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.SearchResult",
+          label: "SearchResult"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.ServingEndpointEntry",
@@ -422,6 +472,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.StreamExecutionSettings",
           label: "StreamExecutionSettings"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.SupervisorApiAdapterOptions",
+          label: "SupervisorApiAdapterOptions"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.SupervisorExtension",
+          label: "SupervisorExtension"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.TelemetryConfig",
@@ -476,6 +536,21 @@ const typedocSidebar: SidebarsConfig = {
           type: "doc",
           id: "api/appkit/Interface.ValidationResult",
           label: "ValidationResult"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.WorkspaceClient",
+          label: "WorkspaceClient"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.WorkspaceClientLike",
+          label: "WorkspaceClientLike"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.WorkspaceClientOptions",
+          label: "WorkspaceClientOptions"
         }
       ]
     },
@@ -513,6 +588,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.ConfigSchema",
           label: "ConfigSchema"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.DatabaseExports",
+          label: "DatabaseExports"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.EvalProgress",
@@ -545,8 +625,8 @@ const typedocSidebar: SidebarsConfig = {
         },
         {
           type: "doc",
-          id: "api/appkit/TypeAlias.JobHandle",
-          label: "JobHandle"
+          id: "api/appkit/TypeAlias.IDatabaseConfig",
+          label: "IDatabaseConfig"
         },
         {
           type: "doc",
@@ -583,6 +663,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.ResourcePermission",
           label: "ResourcePermission"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.SearchFilters",
+          label: "SearchFilters"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ServingFactory",
@@ -593,6 +678,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.Severity",
           label: "Severity"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.SupervisorTool",
+          label: "SupervisorTool"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ToolRegistry",
@@ -614,6 +704,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Variable.agents",
           label: "agents"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Variable.aiSearch",
+          label: "aiSearch"
+        },
         {
           type: "doc",
           id: "api/appkit/Variable.READ_ACTIONS",
@@ -624,6 +719,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Variable.sql",
           label: "sql"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Variable.SUPERVISOR_EXTENSION_KEY",
+          label: "SUPERVISOR_EXTENSION_KEY"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Variable.supervisorTools",
+          label: "supervisorTools"
+        },
         {
           type: "doc",
           id: "api/appkit/Variable.WRITE_ACTIONS",
@@ -650,6 +755,21 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.appKitTypesPlugin",
           label: "appKitTypesPlugin"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.bigid",
+          label: "bigid"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.bigint",
+          label: "bigint"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.boolean",
+          label: "boolean"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.buildAssessments",
@@ -685,6 +805,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.createLakebasePoolManager",
           label: "createLakebasePoolManager"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.createWorkspaceClient",
+          label: "createWorkspaceClient"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.database",
+          label: "database"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.defineEval",
@@ -695,6 +825,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.defineEvalConfig",
           label: "defineEvalConfig"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.defineManifest",
+          label: "defineManifest"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.defineSchema",
+          label: "defineSchema"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.defineTool",
@@ -710,6 +850,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.discoverEvalFiles",
           label: "discoverEvalFiles"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.enumColumn",
+          label: "enumColumn"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.equals",
@@ -740,6 +885,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.findServerFile",
           label: "findServerFile"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.fk",
+          label: "fk"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.formatEvalDetail",
@@ -770,6 +920,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.formatSummaryLine",
           label: "formatSummaryLine"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.fromSupervisorApi",
+          label: "fromSupervisorApi"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.functionToolToDefinition",
@@ -815,11 +970,21 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.getWorkspaceClient",
           label: "getWorkspaceClient"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.id",
+          label: "id"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.includes",
           label: "includes"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.integer",
+          label: "integer"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.isFunctionTool",
@@ -840,11 +1005,21 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.isSQLTypeMarker",
           label: "isSQLTypeMarker"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.isSupervisorTool",
+          label: "isSupervisorTool"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.isToolkitEntry",
           label: "isToolkitEntry"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.jsonb",
+          label: "jsonb"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.loadAgentFromFile",
@@ -910,11 +1085,6 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.runAgent",
           label: "runAgent"
         },
-        {
-          type: "doc",
-          id: "api/appkit/Function.runBounded",
-          label: "runBounded"
-        },
         {
           type: "doc",
           id: "api/appkit/Function.runEval",
@@ -935,6 +1105,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.summarize",
           label: "summarize"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.text",
+          label: "text"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.timestamp",
+          label: "timestamp"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.tool",
@@ -949,6 +1129,16 @@ const typedocSidebar: SidebarsConfig = {
           type: "doc",
           id: "api/appkit/Function.userTurns",
           label: "userTurns"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.uuid",
+          label: "uuid"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Function.varchar",
+          label: "varchar"
         }
       ]
     }