@databricks/appkit 0.72.0 → 0.74.0

package/dist/type-generator/serving/server-file-extractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-file-extractor.js","names":[],"sources":["../../../src/type-generator/serving/server-file-extractor.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\n\nimport { Lang, parse, type SgNode } from \"@ast-grep/napi\";\n\nimport { createLogger } from \"../../logging/logger\";\nimport type { EndpointConfig } from \"../../plugins/serving/types\";\n\nconst logger = createLogger(\"type-generator:serving:extractor\");\n\n/**\n * Candidate paths for the server entry file, relative to the project root.\n * Checked in order; the first that exists is used.\n * Same convention as plugin sync (sync.ts SERVER_FILE_CANDIDATES).\n */\nconst SERVER_FILE_CANDIDATES = [\"server/index.ts\", \"server/server.ts\"];\n\n/**\n * Find the server entry file by checking candidate paths in order.\n *\n * @param basePath - Project root directory to search from\n * @returns Absolute path to the server file, or null if none found\n */\nexport function findServerFile(basePath: string): string | null {\n  for (const candidate of SERVER_FILE_CANDIDATES) {\n    const fullPath = path.join(basePath, candidate);\n    if (fs.existsSync(fullPath)) {\n      return fullPath;\n    }\n  }\n  return null;\n}\n\n/**\n * Extract serving endpoint config from a server file by AST-parsing it.\n * Looks for `serving({ endpoints: { alias: { env: \"...\" }, ... } })` calls\n * and extracts the endpoint alias names and their environment variable mappings.\n *\n * @param serverFilePath - Absolute path to the server entry file\n * @returns Extracted endpoint config, or null if not found or not extractable\n */\nexport function extractServingEndpoints(\n  serverFilePath: string,\n): Record<string, EndpointConfig> | null {\n  let content: string;\n  try {\n    content = fs.readFileSync(serverFilePath, \"utf-8\");\n  } catch {\n    logger.debug(\"Could not read server file: %s\", serverFilePath);\n    return null;\n  }\n\n  const lang = serverFilePath.endsWith(\".tsx\") ? Lang.Tsx : Lang.TypeScript;\n  const ast = parse(lang, content);\n  const root = ast.root();\n\n  // Find serving(...) call expressions\n  const servingCall = findServingCall(root);\n  if (!servingCall) {\n    logger.debug(\"No serving() call found in %s\", serverFilePath);\n    return null;\n  }\n\n  // Get the first argument (the config object)\n  const args = servingCall.field(\"arguments\");\n  if (!args) {\n    return null;\n  }\n\n  const configArg = args.children().find((child) => child.kind() === \"object\");\n  if (!configArg) {\n    // serving() called with no args or non-object arg\n    return null;\n  }\n\n  // Find the \"endpoints\" property in the config object\n  const endpointsPair = findProperty(configArg, \"endpoints\");\n  if (!endpointsPair) {\n    // Config object has no \"endpoints\" property (e.g. serving({ timeout: 5000 }))\n    return null;\n  }\n\n  // Get the value of the endpoints property\n  const endpointsValue = getPropertyValue(endpointsPair);\n  if (!endpointsValue || endpointsValue.kind() !== \"object\") {\n    // endpoints is a variable reference, not an inline object\n    logger.debug(\n      \"serving() endpoints is not an inline object literal in %s. \" +\n        \"Pass endpoints explicitly via appKitServingTypesPlugin({ endpoints }) in vite.config.ts.\",\n      serverFilePath,\n    );\n    return null;\n  }\n\n  // Extract each endpoint entry\n  const endpoints: Record<string, EndpointConfig> = {};\n  const pairs = endpointsValue\n    .children()\n    .filter((child) => child.kind() === \"pair\");\n\n  for (const pair of pairs) {\n    const entry = extractEndpointEntry(pair);\n    if (entry) {\n      endpoints[entry.alias] = entry.config;\n    }\n  }\n\n  if (Object.keys(endpoints).length === 0) {\n    return null;\n  }\n\n  logger.debug(\n    \"Extracted %d endpoint(s) from %s: %s\",\n    Object.keys(endpoints).length,\n    serverFilePath,\n    Object.keys(endpoints).join(\", \"),\n  );\n\n  return endpoints;\n}\n\n/**\n * Find the serving() call expression in the AST.\n * Looks for call expressions where the callee identifier is \"serving\".\n */\nfunction findServingCall(root: SgNode): SgNode | null {\n  const callExpressions = root.findAll({\n    rule: { kind: \"call_expression\" },\n  });\n\n  for (const call of callExpressions) {\n    const callee = call.children()[0];\n    if (callee?.kind() === \"identifier\" && callee.text() === \"serving\") {\n      return call;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Find a property (pair node) with the given key name in an object expression.\n */\nfunction findProperty(objectNode: SgNode, propertyName: string): SgNode | null {\n  const pairs = objectNode\n    .children()\n    .filter((child) => child.kind() === \"pair\");\n\n  for (const pair of pairs) {\n    const key = pair.children()[0];\n    if (!key) continue;\n\n    const keyText =\n      key.kind() === \"property_identifier\"\n        ? key.text()\n        : key.kind() === \"string\"\n          ? key.text().replace(/^['\"]|['\"]$/g, \"\")\n          : null;\n\n    if (keyText === propertyName) {\n      return pair;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get the value node from a pair (property: value).\n * The value is typically the last meaningful child after the colon.\n */\nfunction getPropertyValue(pairNode: SgNode): SgNode | null {\n  const children = pairNode.children();\n  // pair children: [key, \":\", value]\n  return children.length >= 3 ? children[children.length - 1] : null;\n}\n\n/**\n * Extract a single endpoint entry from a pair node like:\n * `demo: { env: \"DATABRICKS_SERVING_ENDPOINT_NAME\", servedModel: \"my-model\" }`\n */\nfunction extractEndpointEntry(\n  pair: SgNode,\n): { alias: string; config: EndpointConfig } | null {\n  const children = pair.children();\n  if (children.length < 3) return null;\n\n  // Get alias name (the key)\n  const keyNode = children[0];\n  const alias =\n    keyNode.kind() === \"property_identifier\"\n      ? keyNode.text()\n      : keyNode.kind() === \"string\"\n        ? keyNode.text().replace(/^['\"]|['\"]$/g, \"\")\n        : null;\n\n  if (!alias) return null;\n\n  // Get the value (should be an object like { env: \"...\" })\n  const valueNode = children[children.length - 1];\n  if (valueNode.kind() !== \"object\") return null;\n\n  // Extract env field\n  const envPair = findProperty(valueNode, \"env\");\n  if (!envPair) return null;\n\n  const envValue = getPropertyValue(envPair);\n  if (!envValue || envValue.kind() !== \"string\") return null;\n\n  const env = envValue.text().replace(/^['\"]|['\"]$/g, \"\");\n\n  // Extract optional servedModel field\n  const config: EndpointConfig = { env };\n  const servedModelPair = findProperty(valueNode, \"servedModel\");\n  if (servedModelPair) {\n    const servedModelValue = getPropertyValue(servedModelPair);\n    if (servedModelValue?.kind() === \"string\") {\n      config.servedModel = servedModelValue.text().replace(/^['\"]|['\"]$/g, \"\");\n    }\n  }\n\n  return { alias, config };\n}\n"],"mappings":"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"}
+{"version":3,"file":"server-file-extractor.js","names":["fs"],"sources":["../../../src/type-generator/serving/server-file-extractor.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\n\nimport { Lang, parse, type SgNode } from \"@ast-grep/napi\";\n\nimport { createLogger } from \"../../logging/logger\";\nimport type { EndpointConfig } from \"../../plugins/serving/types\";\n\nconst logger = createLogger(\"type-generator:serving:extractor\");\n\n/**\n * Candidate paths for the server entry file, relative to the project root.\n * Checked in order; the first that exists is used.\n * Same convention as plugin sync (sync.ts SERVER_FILE_CANDIDATES).\n */\nconst SERVER_FILE_CANDIDATES = [\"server/index.ts\", \"server/server.ts\"];\n\n/**\n * Find the server entry file by checking candidate paths in order.\n *\n * @param basePath - Project root directory to search from\n * @returns Absolute path to the server file, or null if none found\n */\nexport function findServerFile(basePath: string): string | null {\n  for (const candidate of SERVER_FILE_CANDIDATES) {\n    const fullPath = path.join(basePath, candidate);\n    if (fs.existsSync(fullPath)) {\n      return fullPath;\n    }\n  }\n  return null;\n}\n\n/**\n * Extract serving endpoint config from a server file by AST-parsing it.\n * Looks for `serving({ endpoints: { alias: { env: \"...\" }, ... } })` calls\n * and extracts the endpoint alias names and their environment variable mappings.\n *\n * @param serverFilePath - Absolute path to the server entry file\n * @returns Extracted endpoint config, or null if not found or not extractable\n */\nexport function extractServingEndpoints(\n  serverFilePath: string,\n): Record<string, EndpointConfig> | null {\n  let content: string;\n  try {\n    content = fs.readFileSync(serverFilePath, \"utf-8\");\n  } catch {\n    logger.debug(\"Could not read server file: %s\", serverFilePath);\n    return null;\n  }\n\n  const lang = serverFilePath.endsWith(\".tsx\") ? Lang.Tsx : Lang.TypeScript;\n  const ast = parse(lang, content);\n  const root = ast.root();\n\n  // Find serving(...) call expressions\n  const servingCall = findServingCall(root);\n  if (!servingCall) {\n    logger.debug(\"No serving() call found in %s\", serverFilePath);\n    return null;\n  }\n\n  // Get the first argument (the config object)\n  const args = servingCall.field(\"arguments\");\n  if (!args) {\n    return null;\n  }\n\n  const configArg = args.children().find((child) => child.kind() === \"object\");\n  if (!configArg) {\n    // serving() called with no args or non-object arg\n    return null;\n  }\n\n  // Find the \"endpoints\" property in the config object\n  const endpointsPair = findProperty(configArg, \"endpoints\");\n  if (!endpointsPair) {\n    // Config object has no \"endpoints\" property (e.g. serving({ timeout: 5000 }))\n    return null;\n  }\n\n  // Get the value of the endpoints property\n  const endpointsValue = getPropertyValue(endpointsPair);\n  if (!endpointsValue || endpointsValue.kind() !== \"object\") {\n    // endpoints is a variable reference, not an inline object\n    logger.debug(\n      \"serving() endpoints is not an inline object literal in %s. \" +\n        \"Pass endpoints explicitly via appKitServingTypesPlugin({ endpoints }) in vite.config.ts.\",\n      serverFilePath,\n    );\n    return null;\n  }\n\n  // Extract each endpoint entry\n  const endpoints: Record<string, EndpointConfig> = {};\n  const pairs = endpointsValue\n    .children()\n    .filter((child) => child.kind() === \"pair\");\n\n  for (const pair of pairs) {\n    const entry = extractEndpointEntry(pair);\n    if (entry) {\n      endpoints[entry.alias] = entry.config;\n    }\n  }\n\n  if (Object.keys(endpoints).length === 0) {\n    return null;\n  }\n\n  logger.debug(\n    \"Extracted %d endpoint(s) from %s: %s\",\n    Object.keys(endpoints).length,\n    serverFilePath,\n    Object.keys(endpoints).join(\", \"),\n  );\n\n  return endpoints;\n}\n\n/**\n * Find the serving() call expression in the AST.\n * Looks for call expressions where the callee identifier is \"serving\".\n */\nfunction findServingCall(root: SgNode): SgNode | null {\n  const callExpressions = root.findAll({\n    rule: { kind: \"call_expression\" },\n  });\n\n  for (const call of callExpressions) {\n    const callee = call.children()[0];\n    if (callee?.kind() === \"identifier\" && callee.text() === \"serving\") {\n      return call;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Find a property (pair node) with the given key name in an object expression.\n */\nfunction findProperty(objectNode: SgNode, propertyName: string): SgNode | null {\n  const pairs = objectNode\n    .children()\n    .filter((child) => child.kind() === \"pair\");\n\n  for (const pair of pairs) {\n    const key = pair.children()[0];\n    if (!key) continue;\n\n    const keyText =\n      key.kind() === \"property_identifier\"\n        ? key.text()\n        : key.kind() === \"string\"\n          ? key.text().replace(/^['\"]|['\"]$/g, \"\")\n          : null;\n\n    if (keyText === propertyName) {\n      return pair;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get the value node from a pair (property: value).\n * The value is typically the last meaningful child after the colon.\n */\nfunction getPropertyValue(pairNode: SgNode): SgNode | null {\n  const children = pairNode.children();\n  // pair children: [key, \":\", value]\n  return children.length >= 3 ? children[children.length - 1] : null;\n}\n\n/**\n * Extract a single endpoint entry from a pair node like:\n * `demo: { env: \"DATABRICKS_SERVING_ENDPOINT_NAME\", servedModel: \"my-model\" }`\n */\nfunction extractEndpointEntry(\n  pair: SgNode,\n): { alias: string; config: EndpointConfig } | null {\n  const children = pair.children();\n  if (children.length < 3) return null;\n\n  // Get alias name (the key)\n  const keyNode = children[0];\n  const alias =\n    keyNode.kind() === \"property_identifier\"\n      ? keyNode.text()\n      : keyNode.kind() === \"string\"\n        ? keyNode.text().replace(/^['\"]|['\"]$/g, \"\")\n        : null;\n\n  if (!alias) return null;\n\n  // Get the value (should be an object like { env: \"...\" })\n  const valueNode = children[children.length - 1];\n  if (valueNode.kind() !== \"object\") return null;\n\n  // Extract env field\n  const envPair = findProperty(valueNode, \"env\");\n  if (!envPair) return null;\n\n  const envValue = getPropertyValue(envPair);\n  if (!envValue || envValue.kind() !== \"string\") return null;\n\n  const env = envValue.text().replace(/^['\"]|['\"]$/g, \"\");\n\n  // Extract optional servedModel field\n  const config: EndpointConfig = { env };\n  const servedModelPair = findProperty(valueNode, \"servedModel\");\n  if (servedModelPair) {\n    const servedModelValue = getPropertyValue(servedModelPair);\n    if (servedModelValue?.kind() === \"string\") {\n      config.servedModel = servedModelValue.text().replace(/^['\"]|['\"]$/g, \"\");\n    }\n  }\n\n  return { alias, config };\n}\n"],"mappings":"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"}

package/docs/api/appkit/Class.AppKitError.md

@@ -30,6 +30,7 @@ console.error(error.toJSON()); // Safe for logging, sensitive values redacted
 * [`AuthenticationError`](./docs/api/appkit/Class.AuthenticationError.md)
 * [`ConfigurationError`](./docs/api/appkit/Class.ConfigurationError.md)
 * [`ConnectionError`](./docs/api/appkit/Class.ConnectionError.md)
+* [`DatabaseValidationError`](./docs/api/appkit/Class.DatabaseValidationError.md)
 * [`ExecutionError`](./docs/api/appkit/Class.ExecutionError.md)
 * [`InitializationError`](./docs/api/appkit/Class.InitializationError.md)
 * [`ServerError`](./docs/api/appkit/Class.ServerError.md)

package/docs/api/appkit/Class.DatabaseValidationError.md

@@ -0,0 +1,191 @@
+# Class: DatabaseValidationError
+
+Deliberate validation failure raised by a database mutation hook. Generated routes answer `422` and echo only the issues naming a public column; every other failure raised inside a hook stays an opaque server error.
+
+## Extends[​](#extends "Direct link to Extends")
+
+* [`AppKitError`](./docs/api/appkit/Class.AppKitError.md)
+
+## Constructors[​](#constructors "Direct link to Constructors")
+
+### Constructor[​](#constructor "Direct link to Constructor")
+
+```ts
+new DatabaseValidationError(message: string, issues: readonly DatabaseValidationIssue[]): DatabaseValidationError;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                                  | Default value |
+| --------- | ----------------------------------------------------------------------------------------------------- | ------------- |
+| `message` | `string`                                                                                              | `undefined`   |
+| `issues`  | readonly [`DatabaseValidationIssue`](./docs/api/appkit/Interface.DatabaseValidationIssue.md)\[] | `[]`          |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`DatabaseValidationError`
+
+#### Overrides[​](#overrides "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`constructor`](./docs/api/appkit/Class.AppKitError.md#constructor)
+
+## Properties[​](#properties "Direct link to Properties")
+
+### \_clientMessage?[​](#_clientmessage "Direct link to _clientMessage?")
+
+```ts
+protected readonly optional _clientMessage: string;
+
+```
+
+Client-safe error message. When set, callers serializing the error to a client (SSE, HTTP body) MUST prefer `clientMessage` over `message` — `message` may contain raw upstream / SDK text including statement fragments, internal object names, and correlation IDs.
+
+Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`_clientMessage`](./docs/api/appkit/Class.AppKitError.md#_clientmessage)
+
+***
+
+### cause?[​](#cause "Direct link to cause?")
+
+```ts
+readonly optional cause: Error;
+
+```
+
+Optional cause of the error
+
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`cause`](./docs/api/appkit/Class.AppKitError.md#cause)
+
+***
+
+### code[​](#code "Direct link to code")
+
+```ts
+readonly code: "DATABASE_VALIDATION_ERROR" = "DATABASE_VALIDATION_ERROR";
+
+```
+
+Error code for programmatic error handling
+
+#### Overrides[​](#overrides-1 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`code`](./docs/api/appkit/Class.AppKitError.md#code)
+
+***
+
+### context?[​](#context "Direct link to context?")
+
+```ts
+readonly optional context: Record<string, unknown>;
+
+```
+
+Additional context for the error
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`context`](./docs/api/appkit/Class.AppKitError.md#context)
+
+***
+
+### isRetryable[​](#isretryable "Direct link to isRetryable")
+
+```ts
+readonly isRetryable: false = false;
+
+```
+
+Whether this error type is generally safe to retry
+
+#### Overrides[​](#overrides-2 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`isRetryable`](./docs/api/appkit/Class.AppKitError.md#isretryable)
+
+***
+
+### issues[​](#issues "Direct link to issues")
+
+```ts
+readonly issues: readonly DatabaseValidationIssue[];
+
+```
+
+***
+
+### statusCode[​](#statuscode "Direct link to statusCode")
+
+```ts
+readonly statusCode: 422 = 422;
+
+```
+
+HTTP status code suggestion (can be overridden)
+
+#### Overrides[​](#overrides-3 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`statusCode`](./docs/api/appkit/Class.AppKitError.md#statuscode)
+
+## Accessors[​](#accessors "Direct link to Accessors")
+
+### clientMessage[​](#clientmessage "Direct link to clientMessage")
+
+#### Get Signature[​](#get-signature "Direct link to Get Signature")
+
+```ts
+get clientMessage(): string;
+
+```
+
+Sanitized message safe to forward to clients. Override in subclasses if a more specific default is appropriate.
+
+##### Returns[​](#returns-1 "Direct link to Returns")
+
+`string`
+
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`clientMessage`](./docs/api/appkit/Class.AppKitError.md#clientmessage)
+
+## Methods[​](#methods "Direct link to Methods")
+
+### toJSON()[​](#tojson "Direct link to toJSON()")
+
+```ts
+toJSON(): Record<string, unknown>;
+
+```
+
+Convert error to JSON for logging/serialization. Sensitive values in context are automatically redacted.
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`Record`<`string`, `unknown`>
+
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toJSON`](./docs/api/appkit/Class.AppKitError.md#tojson)
+
+***
+
+### toString()[​](#tostring "Direct link to toString()")
+
+```ts
+toString(): string;
+
+```
+
+Create a human-readable string representation
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`string`
+
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toString`](./docs/api/appkit/Class.AppKitError.md#tostring)

package/docs/api/appkit/Function.defineEvalConfig.md

@@ -0,0 +1,18 @@
+# Function: defineEvalConfig()
+
+```ts
+function defineEvalConfig(config: EvalConfig): EvalConfig;
+
+```
+
+Define per-directory eval config. Default-export from `evals.config.ts`.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type         |
+| --------- | ------------ |
+| `config`  | `EvalConfig` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`EvalConfig`

package/docs/api/appkit/Function.defineSchema.md

@@ -5,7 +5,7 @@ function defineSchema<TTables>(builder: (context: SchemaBuilderContext) => TTabl
 
 ```
 
-Compile one declared schema. The returned type keeps the table names the builder returned, so `crudRoutes` and `hooks` can name only real tables.
+Compile one declared schema. The returned type keeps the table names the builder returned, so `api.tables` and `hooks` can name only real tables.
 
 ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
 

package/docs/api/appkit/Function.discoverEvalConfigs.md

@@ -0,0 +1,18 @@
+# Function: discoverEvalConfigs()
+
+```ts
+function discoverEvalConfigs(rootDir: string): DiscoveredEvalConfig[];
+
+```
+
+Discover the per-agent `evals.config.ts` (from [defineEvalConfig](./docs/api/appkit/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.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `rootDir` | `string` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`DiscoveredEvalConfig`](./docs/api/appkit/Interface.DiscoveredEvalConfig.md)\[]

package/docs/api/appkit/Function.formatResultsJUnit.md

@@ -0,0 +1,18 @@
+# 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[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `results` | [`EvalResult`](./docs/api/appkit/Interface.EvalResult.md)\[] |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string`

package/docs/api/appkit/Function.formatResultsJson.md

@@ -0,0 +1,18 @@
+# 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[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `results` | [`EvalResult`](./docs/api/appkit/Interface.EvalResult.md)\[] |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string`

package/docs/api/appkit/Function.readEvalDataset.md

@@ -0,0 +1,21 @@
+# 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[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                    |
+| --------- | --------------------------------------------------------------------------------------- |
+| `client`  | [`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md)               |
+| `options` | [`ReadEvalDatasetOptions`](./docs/api/appkit/Interface.ReadEvalDatasetOptions.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`DatasetRow`](./docs/api/appkit/Interface.DatasetRow.md)\[]>

package/docs/api/appkit/Function.resolveWorkspaceClient.md

@@ -0,0 +1,18 @@
+# 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[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| `options` | [`ResolveDatabricksAuthOptions`](./docs/api/appkit/Interface.ResolveDatabricksAuthOptions.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md) | `undefined`

package/docs/api/appkit/Function.runWithRetries.md

@@ -0,0 +1,28 @@
+# Function: runWithRetries()
+
+```ts
+function runWithRetries(
+   retries: number, 
+   attempt: (attemptNumber: number) => Promise<EvalResult>, 
+   options: {
+  baseDelayMs?: number;
+}): Promise<EvalResult>;
+
+```
+
+Run `attempt` up to `1 + retries` times, stopping as soon as it returns a result that is neither a thrown error / per-eval timeout (`error`) nor a transport/agent turn failure (`infraFailure`). Assertion failures set neither, so a failed-but-completed eval is returned on the first try and never retried. Returns the last result when every attempt failed on infra.
+
+Between attempts it waits a full-jittered exponential backoff (infra flakes are overload-correlated). `retries` is coerced to a finite non-negative integer; `baseDelayMs: 0` disables the wait (tests).
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter              | Type                                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `retries`              | `number`                                                                                                  |
+| `attempt`              | (`attemptNumber`: `number`) => `Promise`<[`EvalResult`](./docs/api/appkit/Interface.EvalResult.md)> |
+| `options`              | { `baseDelayMs?`: `number`; }                                                                             |
+| `options.baseDelayMs?` | `number`                                                                                                  |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Promise`<[`EvalResult`](./docs/api/appkit/Interface.EvalResult.md)>

package/docs/api/appkit/Function.userTurns.md

@@ -0,0 +1,20 @@
+# 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[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `input`   | `Record`<`string`, `unknown`> |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string`\[]

package/docs/api/appkit/Interface.AssertionHandle.md

@@ -11,7 +11,7 @@ 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[​](#parameters "Direct link to Parameters")
 

package/docs/api/appkit/Interface.DatabaseValidationIssue.md

@@ -0,0 +1,21 @@
+# Interface: DatabaseValidationIssue
+
+One rejected field; `path` names public columns, never their values.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### message[​](#message "Direct link to message")
+
+```ts
+readonly message: string;
+
+```
+
+***
+
+### path[​](#path "Direct link to path")
+
+```ts
+readonly path: readonly string[];
+
+```

package/docs/api/appkit/Interface.DatasetRow.md

@@ -0,0 +1,21 @@
+# 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[​](#properties "Direct link to Properties")
+
+### expectations?[​](#expectations "Direct link to expectations?")
+
+```ts
+optional expectations: Record<string, unknown>;
+
+```
+
+***
+
+### inputs[​](#inputs "Direct link to inputs")
+
+```ts
+inputs: Record<string, unknown>;
+
+```

package/docs/api/appkit/Interface.DiscoveredEvalConfig.md

@@ -0,0 +1,25 @@
+# Interface: DiscoveredEvalConfig
+
+A per-agent `evals.config.ts` found under `server/agents/<agent>/evals/`.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agent[​](#agent "Direct link to agent")
+
+```ts
+agent: string;
+
+```
+
+The agent id whose evals this config applies to.
+
+***
+
+### file[​](#file "Direct link to file")
+
+```ts
+file: string;
+
+```
+
+Absolute path to the `evals.config.ts` file.

package/docs/api/appkit/Interface.DriveResult.md

@@ -37,6 +37,34 @@ Whether the turn completed without an agent/stream error.
 
 ***
 
+### toolCallDetails[​](#toolcalldetails "Direct link to toolCallDetails")
+
+```ts
+toolCallDetails: {
+  args: Record<string, unknown>;
+  name: string;
+}[];
+
+```
+
+Tool calls with their parsed arguments, in call order.
+
+#### args[​](#args "Direct link to args")
+
+```ts
+args: Record<string, unknown>;
+
+```
+
+#### name[​](#name "Direct link to name")
+
+```ts
+name: string;
+
+```
+
+***
+
 ### toolCalls[​](#toolcalls "Direct link to toolCalls")
 
 ```ts