@databricks/appkit 0.54.0 → 0.55.1

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

@@ -0,0 +1,64 @@
+# Interface: SearchRequest
+
+## Properties[​](#properties "Direct link to Properties")
+
+### columns?[​](#columns "Direct link to columns?")
+
+```ts
+optional columns: string[];
+
+```
+
+***
+
+### filters?[​](#filters "Direct link to filters?")
+
+```ts
+optional filters: SearchFilters;
+
+```
+
+***
+
+### numResults?[​](#numresults "Direct link to numResults?")
+
+```ts
+optional numResults: number;
+
+```
+
+***
+
+### queryText?[​](#querytext "Direct link to queryText?")
+
+```ts
+optional queryText: string;
+
+```
+
+***
+
+### queryType?[​](#querytype "Direct link to queryType?")
+
+```ts
+optional queryType: SearchQueryType;
+
+```
+
+***
+
+### queryVector?[​](#queryvector "Direct link to queryVector?")
+
+```ts
+optional queryVector: number[];
+
+```
+
+***
+
+### reranker?[​](#reranker "Direct link to reranker?")
+
+```ts
+optional reranker: boolean;
+
+```

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

@@ -0,0 +1,52 @@
+# Interface: SearchResponse\<T>
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                              | Default type                  |
+| ------------------------------------------- | ----------------------------- |
+| `T` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### nextPageToken[​](#nextpagetoken "Direct link to nextPageToken")
+
+```ts
+nextPageToken: string | null;
+
+```
+
+***
+
+### queryTimeMs[​](#querytimems "Direct link to queryTimeMs")
+
+```ts
+queryTimeMs: number;
+
+```
+
+***
+
+### queryType[​](#querytype "Direct link to queryType")
+
+```ts
+queryType: SearchQueryType;
+
+```
+
+***
+
+### results[​](#results "Direct link to results")
+
+```ts
+results: SearchResult<T>[];
+
+```
+
+***
+
+### totalCount[​](#totalcount "Direct link to totalCount")
+
+```ts
+totalCount: number;
+
+```

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

@@ -0,0 +1,25 @@
+# Interface: SearchResult\<T>
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                              | Default type                  |
+| ------------------------------------------- | ----------------------------- |
+| `T` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### data[​](#data "Direct link to data")
+
+```ts
+data: T;
+
+```
+
+***
+
+### score[​](#score "Direct link to score")
+
+```ts
+score: number;
+
+```

package/docs/api/appkit/TypeAlias.JobsExport.md

@@ -1,7 +1,7 @@
 # Type Alias: JobsExport()
 
 ```ts
-type JobsExport = (jobKey: string) => JobHandle;
+type JobsExport = (jobKey: string) => JobAPI;
 
 ```
 
@@ -15,7 +15,7 @@ Public API shape of the jobs plugin. Callable to select a job by key.
 
 ## Returns[​](#returns "Direct link to Returns")
 
-[`JobHandle`](./docs/api/appkit/TypeAlias.JobHandle.md)
+[`JobAPI`](./docs/api/appkit/Interface.JobAPI.md)
 
 ## Example[​](#example "Direct link to Example")
 
@@ -28,7 +28,4 @@ for await (const status of appkit.jobs("etl").runAndWait()) {
   console.log(status.status, status.run);
 }
 
-// OBO access
-await appkit.jobs("etl").asUser(req).runNow();
-
 ```

package/docs/api/appkit/TypeAlias.SearchFilters.md

@@ -0,0 +1,6 @@
+# Type Alias: SearchFilters
+
+```ts
+type SearchFilters = Record<string, string | number | boolean | (string | number)[]>;
+
+```

package/docs/api/appkit/Variable.aiSearch.md

@@ -0,0 +1,6 @@
+# Variable: aiSearch
+
+```ts
+const aiSearch: ToPlugin<typeof AiSearchPlugin, IAiSearchConfig, "aiSearch">;
+
+```

package/docs/api/appkit.md

@@ -50,7 +50,9 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [GenerationParams](./docs/api/appkit/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](./docs/api/appkit/Interface.HostedSupervisorTool.md)                           | Tagged record returned by every [supervisorTools](./docs/api/appkit/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). |
+| [IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md)                                     | Base configuration interface for AppKit plugins                                                                                                                                                                                                                                                                                                                                                                                                               |
 | [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md)                                             | Configuration for the Jobs plugin.                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [IndexConfig](./docs/api/appkit/Interface.IndexConfig.md)                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                                                                                                                                                                                                                   |
 | [JobAPI](./docs/api/appkit/Interface.JobAPI.md)                                                       | User-facing API for a single configured job.                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [JobConfig](./docs/api/appkit/Interface.JobConfig.md)                                                 | Per-job configuration options.                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -66,10 +68,14 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md)                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [RequestedClaims](./docs/api/appkit/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](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [RerankerConfig](./docs/api/appkit/Interface.RerankerConfig.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                                                                                                                                                                                                                |
 | [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().                                                                                                                                                                                                                                                                                                                           |
 | [RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md)                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [SearchRequest](./docs/api/appkit/Interface.SearchRequest.md)                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [SearchResponse](./docs/api/appkit/Interface.SearchResponse.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [SearchResult](./docs/api/appkit/Interface.SearchResult.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md)                           | Shape of a single registry entry.                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ServingEndpointRegistry](./docs/api/appkit/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](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                                                                                                                                                                                                                    |
@@ -104,13 +110,13 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md)                         | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny.                                                                                                                                                                                             |
 | [HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md)                         | -                                                                                                                                                                                                                                                                                                                      |
 | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                         | Express router type for plugin route registration                                                                                                                                                                                                                                                                      |
-| [JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md)                           | Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`.                                                                                                                                                                                                                                   |
 | [JobsExport](./docs/api/appkit/TypeAlias.JobsExport.md)                         | Public API shape of the jobs plugin. Callable to select a job by key.                                                                                                                                                                                                                                                  |
 | [PluginData](./docs/api/appkit/TypeAlias.PluginData.md)                         | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.                                                                                                                                                                                                                          |
 | [Plugins](./docs/api/appkit/TypeAlias.Plugins.md)                               | Plugin map passed to the function form of [AgentDefinition.tools](./docs/api/appkit/Interface.AgentDefinition.md#tools). Each entry exposes a `.toolkit(opts?)` method that returns a record of [ToolkitEntry](./docs/api/appkit/Interface.ToolkitEntry.md) markers ready to be spread into a tool record. |
 | [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md)           | Internal tool-index entry after a tool record has been resolved to a dispatchable form.                                                                                                                                                                                                                                |
 | [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)         | -                                                                                                                                                                                                                                                                                                                      |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md)         | Union of all possible permission levels across all resource types.                                                                                                                                                                                                                                                     |
+| [SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md)                   | -                                                                                                                                                                                                                                                                                                                      |
 | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)                 | Factory function returned by `AppKit.serving`.                                                                                                                                                                                                                                                                         |
 | [SupervisorTool](./docs/api/appkit/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](./docs/api/appkit/TypeAlias.ToolRegistry.md)                     | -                                                                                                                                                                                                                                                                                                                      |
@@ -121,6 +127,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | Variable                                                                                   | Description                                                                                                                                                                                                                                                                                                    |
 | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [agents](./docs/api/appkit/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). |
+| [aiSearch](./docs/api/appkit/Variable.aiSearch.md)                                   | -                                                                                                                                                                                                                                                                                                              |
 | [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md)                          | Actions that only read data.                                                                                                                                                                                                                                                                                   |
 | [sql](./docs/api/appkit/Variable.sql.md)                                             | SQL helper namespace                                                                                                                                                                                                                                                                                           |
 | [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads.                          |

package/docs/plugins/{vector-search.md → ai-search.md}

@@ -1,4 +1,8 @@
-# Vector Search plugin
+# AI Search plugin
+
+Beta plugin
+
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
 
 Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
@@ -14,12 +18,13 @@ Query Databricks Vector Search indexes with hybrid search, reranking, and cursor
 ## Basic usage[​](#basic-usage "Direct link to Basic usage")
 
 ```ts
-import { createApp, vectorSearch, server } from "@databricks/appkit";
+import { createApp, server } from "@databricks/appkit";
+import { aiSearch } from "@databricks/appkit/beta";
 
 await createApp({
   plugins: [
     server(),
-    vectorSearch({
+    aiSearch({
       indexes: {
         products: {
           indexName: "catalog.schema.products_idx",
@@ -46,7 +51,7 @@ await createApp({
 Index aliases let you reference multiple Vector Search indexes by name. The alias is used in API routes and programmatic calls:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -62,19 +67,23 @@ vectorSearch({
 
 ```
 
+note
+
+An alias without its own `indexName` falls back to the `DATABRICKS_VS_INDEX_NAME` env var. If several aliases omit `indexName`, they all resolve to that one physical index (with their own per-alias `columns`, `queryType`, etc.). Give each alias an explicit `indexName` when you mean distinct indexes.
+
 ## IndexConfig[​](#indexconfig "Direct link to IndexConfig")
 
-| Field          | Type                                         | Default               | Description                                                                     |
-| -------------- | -------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- |
-| `indexName`    | `string`                                     | —                     | **Required.** Three-level Unity Catalog name (`catalog.schema.index`)           |
-| `columns`      | `string[]`                                   | —                     | **Required.** Columns to return in query results                                |
-| `queryType`    | `"ann" \| "hybrid" \| "full_text"`           | `"hybrid"`            | Search mode                                                                     |
-| `numResults`   | `number`                                     | `20`                  | Maximum results per query                                                       |
-| `reranker`     | `boolean \| { columnsToRerank: string[] }`   | —                     | Enable reranking. Pass `true` to rerank all result columns, or specify a subset |
-| `auth`         | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"` | Authentication mode for query execution                                         |
-| `pagination`   | `boolean`                                    | —                     | Enable cursor-based pagination                                                  |
-| `endpointName` | `string`                                     | —                     | Vector Search endpoint name. Required when `pagination` is `true`               |
-| `embeddingFn`  | `(text: string) => Promise<number[]>`        | —                     | Custom embedding function for self-managed embedding indexes                    |
+| Field          | Type                                         | Default                    | Description                                                                                                                                                                                                             |
+| -------------- | -------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `indexName`    | `string`                                     | `DATABRICKS_VS_INDEX_NAME` | Three-level Unity Catalog name (`catalog.schema.index`). Defaults to the `DATABRICKS_VS_INDEX_NAME` env var when omitted.                                                                                               |
+| `columns`      | `string[]`                                   | auto-discovered in dev     | Columns to return in query results. Optional in development — when omitted, the plugin reads them from the index's source table and warns. **Set explicitly for production**, where a missing value is not auto-filled. |
+| `queryType`    | `"ann" \| "hybrid" \| "full_text"`           | `"hybrid"`                 | Search mode                                                                                                                                                                                                             |
+| `numResults`   | `number`                                     | `20`                       | Maximum results per query                                                                                                                                                                                               |
+| `reranker`     | `boolean \| { columnsToRerank: string[] }`   | —                          | Enable reranking. Pass `true` to rerank all result columns, or specify a subset                                                                                                                                         |
+| `auth`         | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"`      | Authentication mode for query execution                                                                                                                                                                                 |
+| `pagination`   | `boolean`                                    | —                          | Enable cursor-based pagination                                                                                                                                                                                          |
+| `endpointName` | `string`                                     | —                          | Vector Search endpoint name. Required when `pagination` is `true`                                                                                                                                                       |
+| `embeddingFn`  | `(text: string) => Promise<number[]>`        | —                          | Custom embedding function for self-managed embedding indexes                                                                                                                                                            |
 
 ### Query types[​](#query-types "Direct link to Query types")
 
@@ -87,7 +96,7 @@ vectorSearch({
 Reranking improves result relevance by running a second-stage model over the initial candidates:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -106,7 +115,7 @@ Pass `reranker: true` to rerank across all returned columns.
 By default, queries run as the app's service principal. Set `auth: "on-behalf-of-user"` to execute queries as the signed-in user instead:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     documents: {
       indexName: "catalog.schema.documents_idx",
@@ -123,7 +132,7 @@ vectorSearch({
 Enable cursor pagination to page through large result sets:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -145,7 +154,7 @@ For indexes that manage their own embeddings, provide an `embeddingFn` that take
 ```ts
 import { embed } from "./my-embedding-client";
 
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -160,7 +169,7 @@ vectorSearch({
 
 ## HTTP routes[​](#http-routes "Direct link to HTTP routes")
 
-Routes are mounted at `/api/vector-search`.
+Routes are mounted at `/api/ai-search`.
 
 | Method | Path                | Description                                                  |
 | ------ | ------------------- | ------------------------------------------------------------ |
@@ -171,7 +180,7 @@ Routes are mounted at `/api/vector-search`.
 ### Query an index[​](#query-an-index "Direct link to Query an index")
 
 ```text
-POST /api/vector-search/:alias/query
+POST /api/ai-search/:alias/query
 Content-Type: application/json
 
 {
@@ -186,19 +195,25 @@ Response:
 ```json
 {
   "results": [
-    { "id": "42", "name": "Intro to ML", "description": "..." }
+    {
+      "score": 0.87,
+      "data": { "id": "42", "name": "Intro to ML", "description": "..." }
+    }
   ],
+  "totalCount": 1,
+  "queryTimeMs": 35,
+  "queryType": "hybrid",
   "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
 }
 
 ```
 
-`nextPageToken` is only present when `pagination` is enabled and more results are available.
+Each result carries its relevance `score` and the returned columns under `data`. `nextPageToken` is `null` unless `pagination` is enabled and more results are available.
 
 ### Fetch the next page[​](#fetch-the-next-page "Direct link to Fetch the next page")
 
 ```text
-POST /api/vector-search/:alias/next-page
+POST /api/ai-search/:alias/next-page
 Content-Type: application/json
 
 {
@@ -211,7 +226,7 @@ Content-Type: application/json
 ### Get index config[​](#get-index-config "Direct link to Get index config")
 
 ```text
-GET /api/vector-search/:alias/config
+GET /api/ai-search/:alias/config
 
 ```
 
@@ -222,10 +237,13 @@ Returns the resolved `IndexConfig` for the alias (excluding `embeddingFn`).
 The plugin exposes a `query` method for server-side use:
 
 ```ts
+import { createApp, server } from "@databricks/appkit";
+import { aiSearch } from "@databricks/appkit/beta";
+
 const AppKit = await createApp({
   plugins: [
     server(),
-    vectorSearch({
+    aiSearch({
       indexes: {
         products: {
           indexName: "catalog.schema.products_idx",
@@ -236,7 +254,7 @@ const AppKit = await createApp({
   ],
 });
 
-const result = await AppKit.vectorSearch.query("products", {
+const result = await AppKit.aiSearch.query("products", {
   queryText: "machine learning guide",
 });
 
@@ -245,3 +263,28 @@ console.log(result.results);
 ```
 
 Pass optional overrides as a second argument to `query` to adjust `numResults` or other per-call settings.
+
+## React hook[​](#react-hook "Direct link to React hook")
+
+`useAiSearchQuery` reads the configured indexes from the plugin's client config and posts to the right `/:alias/query` route, so the UI never hardcodes an alias. With one index configured it needs no arguments; pass `{ alias }` to target a specific one.
+
+```tsx
+import { useAiSearchQuery } from "@databricks/appkit-ui/react/beta";
+
+function Search() {
+  const { search, data, loading, error } = useAiSearchQuery();
+
+  return (
+    <>
+      <input onKeyDown={(e) => e.key === "Enter" && search(e.currentTarget.value)} />
+      {error && <p>{error}</p>}
+      {data?.results.map((r, i) => (
+        <div key={i}>{JSON.stringify(r.data)}</div>
+      ))}
+    </>
+  );
+}
+
+```
+
+`search` also accepts a full request object (`{ queryText, numResults, filters, ... }`) for per-call control. The hook's `indexes` field lists every configured index, which you can use to build an index picker.

package/docs/plugins/jobs.md

@@ -9,7 +9,6 @@ Trigger and monitor [Databricks Lakeflow Jobs](https://docs.databricks.com/en/jo
 * Run-and-wait with SSE streaming status updates
 * Parameter validation with Zod schemas
 * Task-type-aware parameter mapping (notebook, python\_wheel, sql, etc.)
-* Optional on-behalf-of (OBO) user execution via `.asUser(req)`
 
 ## Basic usage[​](#basic-usage "Direct link to Basic usage")
 
@@ -127,19 +126,7 @@ When `taskType` is omitted, parameters are passed through to the SDK as-is.
 
 ## Execution context[​](#execution-context "Direct link to Execution context")
 
-HTTP routes run as the **app's service principal** by default. Jobs are typically shared infrastructure, and the app's resource binding (`databricks.yml`) grants `CAN_MANAGE_RUN` to the SP — so users trigger runs without needing individual grants.
-
-Per-run attribution in the Jobs UI will show the app's SP, not the human user. If you need user-level attribution (or want the Databricks permission check to use the user's grants), opt in to OBO explicitly in a custom handler via `.asUser(req)`:
-
-```ts
-// Default: runs as the app's service principal
-const result = await AppKit.jobs("etl").runNow({ startDate: "2025-01-01" });
-
-// Opt-in: runs as the logged-in user (requires `jobs.jobs` in
-// `databricks.yml` user_api_scopes AND the user's own CAN_MANAGE_RUN grant)
-const result = await AppKit.jobs("etl").asUser(req).runNow({ startDate: "2025-01-01" });
-
-```
+Jobs always run as the **app's service principal**. The app's resource binding (`databricks.yml`) grants `CAN_MANAGE_RUN` to the SP, so users trigger runs without needing individual grants. Per-run attribution in the Jobs UI shows the app's SP, not the human user.
 
 ## HTTP endpoints[​](#http-endpoints "Direct link to HTTP endpoints")
 

package/llms.txt

@@ -44,6 +44,7 @@ npx @databricks/appkit docs <query>
 ## Plugins
 
 - [Agents](./docs/plugins/agents.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
+- [AI Search plugin](./docs/plugins/ai-search.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
 - [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
@@ -57,7 +58,6 @@ npx @databricks/appkit docs <query>
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
 - [Plugin Stability Tiers](./docs/plugins/stability.md): AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
-- [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
 ## appkit API reference [collapsed]
 
@@ -131,7 +131,9 @@ npx @databricks/appkit docs <query>
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
 - [Interface: HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md): Tagged record returned by every supervisorTools factory. The
+- [Interface: IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md): Base configuration interface for AppKit plugins
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
+- [Interface: IndexConfig](./docs/api/appkit/Interface.IndexConfig.md): Properties
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
 - [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
@@ -147,10 +149,14 @@ npx @databricks/appkit docs <query>
 - [Interface: RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md): Properties
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
 - [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
+- [Interface: RerankerConfig](./docs/api/appkit/Interface.RerankerConfig.md): Properties
 - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
 - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
 - [Interface: RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md): Properties
 - [Interface: RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md): Properties
+- [Interface: SearchRequest](./docs/api/appkit/Interface.SearchRequest.md): Properties
+- [Interface: SearchResponse<T>](./docs/api/appkit/Interface.SearchResponse.md): Type Parameters
+- [Interface: SearchResult<T>](./docs/api/appkit/Interface.SearchResult.md): Type Parameters
 - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
 - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
@@ -180,18 +186,19 @@ npx @databricks/appkit docs <query>
 - [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on
 - [Type Alias: HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md)
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
-- [Type Alias: JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md): Job handle returned by appkit.jobs("etl").
 - [Type Alias: JobsExport()](./docs/api/appkit/TypeAlias.JobsExport.md): Public API shape of the jobs plugin.
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
 - [Type Alias: Plugins](./docs/api/appkit/TypeAlias.Plugins.md): Plugin map passed to the function form of AgentDefinition.tools.
 - [Type Alias: ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md): Internal tool-index entry after a tool record has been resolved to a dispatchable form.
 - [Type Alias: ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
+- [Type Alias: SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md)
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
 - [Type Alias: SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md): Tools supported by the Databricks AI Gateway Responses API. The shapes match
 - [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
 - [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
+- [Variable: aiSearch](./docs/api/appkit/Variable.aiSearch.md)
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
 - [Variable: SUPERVISOR_EXTENSION_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md): Namespace key under which the adapter reads its hosted-tool payload

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.54.0",
+  "version": "0.55.1",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {