@databricks/appkit-ui 0.31.0 → 0.33.0

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

@@ -0,0 +1,22 @@
+# Interface: PluginToolkitProvider
+
+Minimum shape every entry in the [Plugins](./docs/api/appkit/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).
+
+## Methods[​](#methods "Direct link to Methods")
+
+### toolkit()[​](#toolkit "Direct link to toolkit()")
+
+```ts
+toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                    |
+| --------- | ----------------------------------------------------------------------- |
+| `opts?`   | [`ToolkitOptions`](./docs/api/appkit/Interface.ToolkitOptions.md) |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Record`<`string`, [`ToolkitEntry`](./docs/api/appkit/Interface.ToolkitEntry.md)>

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

@@ -0,0 +1,30 @@
+# Interface: PromptContext
+
+Context passed to `baseSystemPrompt` callbacks.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### agentName[​](#agentname "Direct link to agentName")
+
+```ts
+agentName: string;
+
+```
+
+***
+
+### pluginNames[​](#pluginnames "Direct link to pluginNames")
+
+```ts
+pluginNames: string[];
+
+```
+
+***
+
+### toolNames[​](#toolnames "Direct link to toolNames")
+
+```ts
+toolNames: string[];
+
+```

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

@@ -0,0 +1,75 @@
+# Interface: RegisteredAgent
+
+## Properties[​](#properties "Direct link to Properties")
+
+### adapter[​](#adapter "Direct link to adapter")
+
+```ts
+adapter: AgentAdapter;
+
+```
+
+***
+
+### baseSystemPrompt?[​](#basesystemprompt "Direct link to baseSystemPrompt?")
+
+```ts
+optional baseSystemPrompt: BaseSystemPromptOption;
+
+```
+
+***
+
+### ephemeral?[​](#ephemeral "Direct link to ephemeral?")
+
+```ts
+optional ephemeral: boolean;
+
+```
+
+Mirrors `AgentDefinition.ephemeral` — skip thread persistence.
+
+***
+
+### instructions[​](#instructions "Direct link to instructions")
+
+```ts
+instructions: string;
+
+```
+
+***
+
+### maxSteps?[​](#maxsteps "Direct link to maxSteps?")
+
+```ts
+optional maxSteps: number;
+
+```
+
+***
+
+### maxTokens?[​](#maxtokens "Direct link to maxTokens?")
+
+```ts
+optional maxTokens: number;
+
+```
+
+***
+
+### name[​](#name "Direct link to name")
+
+```ts
+name: string;
+
+```
+
+***
+
+### toolIndex[​](#toolindex "Direct link to toolIndex")
+
+```ts
+toolIndex: Map<string, ResolvedToolEntry>;
+
+```

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

@@ -0,0 +1,34 @@
+# Interface: RunAgentInput
+
+## Properties[​](#properties "Direct link to Properties")
+
+### messages[​](#messages "Direct link to messages")
+
+```ts
+messages: string | Message[];
+
+```
+
+Seed messages for the run. Either a single user string or a full message list.
+
+***
+
+### plugins?[​](#plugins "Direct link to plugins?")
+
+```ts
+optional plugins: PluginData<PluginConstructor, unknown, string>[];
+
+```
+
+Optional plugin list. Required when `def.tools` is the function form `(plugins) => Record<string, AgentTool>` and the function dereferences any plugins. `runAgent` constructs a fresh instance per plugin and dispatches tool calls against it as the service principal (no OBO — there is no HTTP request in standalone mode).
+
+***
+
+### signal?[​](#signal "Direct link to signal?")
+
+```ts
+optional signal: AbortSignal;
+
+```
+
+Abort signal for cancellation.

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

@@ -0,0 +1,23 @@
+# Interface: RunAgentResult
+
+## Properties[​](#properties "Direct link to Properties")
+
+### events[​](#events "Direct link to events")
+
+```ts
+events: AgentEvent[];
+
+```
+
+Every event the adapter yielded, in order. Useful for inspection/tests.
+
+***
+
+### text[​](#text "Direct link to text")
+
+```ts
+text: string;
+
+```
+
+Aggregated text output from all `message_delta` events.

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

@@ -0,0 +1,46 @@
+# Interface: Thread
+
+## Properties[​](#properties "Direct link to Properties")
+
+### createdAt[​](#createdat "Direct link to createdAt")
+
+```ts
+createdAt: Date;
+
+```
+
+***
+
+### id[​](#id "Direct link to id")
+
+```ts
+id: string;
+
+```
+
+***
+
+### messages[​](#messages "Direct link to messages")
+
+```ts
+messages: Message[];
+
+```
+
+***
+
+### updatedAt[​](#updatedat "Direct link to updatedAt")
+
+```ts
+updatedAt: Date;
+
+```
+
+***
+
+### userId[​](#userid "Direct link to userId")
+
+```ts
+userId: string;
+
+```

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

@@ -0,0 +1,103 @@
+# Interface: ThreadStore
+
+## Methods[​](#methods "Direct link to Methods")
+
+### addMessage()[​](#addmessage "Direct link to addMessage()")
+
+```ts
+addMessage(
+   threadId: string, 
+   userId: string, 
+message: Message): Promise<void>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                                                      |
+| ---------- | --------------------------------------------------------- |
+| `threadId` | `string`                                                  |
+| `userId`   | `string`                                                  |
+| `message`  | [`Message`](./docs/api/appkit/Interface.Message.md) |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`void`>
+
+***
+
+### create()[​](#create "Direct link to create()")
+
+```ts
+create(userId: string): Promise<Thread>;
+
+```
+
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `userId`  | `string` |
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+`Promise`<[`Thread`](./docs/api/appkit/Interface.Thread.md)>
+
+***
+
+### delete()[​](#delete "Direct link to delete()")
+
+```ts
+delete(threadId: string, userId: string): Promise<boolean>;
+
+```
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `threadId` | `string` |
+| `userId`   | `string` |
+
+#### Returns[​](#returns-2 "Direct link to Returns")
+
+`Promise`<`boolean`>
+
+***
+
+### get()[​](#get "Direct link to get()")
+
+```ts
+get(threadId: string, userId: string): Promise<Thread | null>;
+
+```
+
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `threadId` | `string` |
+| `userId`   | `string` |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`Promise`<[`Thread`](./docs/api/appkit/Interface.Thread.md) | `null`>
+
+***
+
+### list()[​](#list "Direct link to list()")
+
+```ts
+list(userId: string): Promise<Thread[]>;
+
+```
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `userId`  | `string` |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`Promise`<[`Thread`](./docs/api/appkit/Interface.Thread.md)\[]>

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

@@ -0,0 +1,56 @@
+# Interface: ToolAnnotations
+
+## Properties[​](#properties "Direct link to Properties")
+
+### ~~destructive?~~[​](#destructive "Direct link to destructive")
+
+```ts
+optional destructive: boolean;
+
+```
+
+#### Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Prefer [effect](#effect) with value `"destructive"`. Retained so existing annotations continue to force the approval gate, and so MCP-style consumers that only read `destructive` still see the hint.
+
+***
+
+### effect?[​](#effect "Direct link to effect?")
+
+```ts
+optional effect: ToolEffect;
+
+```
+
+Preferred semantic label. When set, drives both the approval gate (fires for `write`/`update`/`destructive`) and the approval-card styling.
+
+***
+
+### idempotent?[​](#idempotent "Direct link to idempotent?")
+
+```ts
+optional idempotent: boolean;
+
+```
+
+***
+
+### ~~readOnly?~~[​](#readonly "Direct link to readonly")
+
+```ts
+optional readOnly: boolean;
+
+```
+
+#### Deprecated[​](#deprecated-1 "Direct link to Deprecated")
+
+Prefer [effect](#effect). Retained for backward compatibility with tools authored against the original flags and for MCP interop.
+
+***
+
+### requiresUserContext?[​](#requiresusercontext "Direct link to requiresUserContext?")
+
+```ts
+optional requiresUserContext: boolean;
+
+```

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

@@ -0,0 +1,72 @@
+# Interface: ToolConfig\<S>
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter            |
+| ------------------------- |
+| `S` *extends* `z.ZodType` |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+Behavioural hints forwarded to the resolved tool definition. Prefer `effect` (`"read" | "write" | "update" | "destructive"`) — any mutating value forces the agents-plugin approval gate before `execute()` runs and the client's approval card will colour itself accordingly. Legacy `destructive: true` still gates. Dropped silently before the fix that added this field.
+
+***
+
+### description[​](#description "Direct link to description")
+
+```ts
+description: string;
+
+```
+
+What the tool does, what it expects, and when the LLM should call it. The model reads this verbatim when deciding whether to invoke the tool, so write it for an LLM, not for a human reader of your code: spell out the inputs, the return shape, and any pre-conditions or side effects.
+
+Required. Earlier versions silently fell back to the tool's name when omitted, which surfaced cryptic identifiers like `"get_weather"` as the description — the model then had no signal about expected use and either skipped the tool or called it speculatively. Making this mandatory at the type level forces a real description at authoring time instead of debugging a confused agent later.
+
+***
+
+### execute()[​](#execute "Direct link to execute()")
+
+```ts
+execute: (args: output<S>) => unknown;
+
+```
+
+Returning a non-string value is fine: the agent runtime serializes the result via `normalizeToolResult` before handing it to the LLM (strings pass through; `null` becomes `"null"`; everything else gets `JSON.stringify`'d; `undefined` becomes `""`). Return whatever shape is most natural for your tool — typically an object — and let the runtime handle the wire format.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `args`    | `output`<`S`> |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`unknown`
+
+***
+
+### name?[​](#name "Direct link to name?")
+
+```ts
+optional name: string;
+
+```
+
+Optional. When the tool is placed in a keyed record (the standard `tools: { my_tool: tool({...}) }` form, or the function form `tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin overrides the tool's LLM-visible name with the record key. Set `name` explicitly only if you're constructing a `FunctionTool` outside any keyed-record context — otherwise the record key wins.
+
+***
+
+### schema[​](#schema "Direct link to schema")
+
+```ts
+schema: S;
+
+```

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

@@ -0,0 +1,73 @@
+# Interface: ToolEntry\<S>
+
+Single-tool entry for a plugin's internal tool registry.
+
+Plugins collect these into a `Record<string, ToolEntry>` keyed by the tool's public name and dispatch via `executeFromRegistry`.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter            | Default type |
+| ------------------------- | ------------ |
+| `S` *extends* `z.ZodType` | `z.ZodType`  |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+***
+
+### autoInheritable?[​](#autoinheritable "Direct link to autoInheritable?")
+
+```ts
+optional autoInheritable: boolean;
+
+```
+
+Whether this tool is eligible for auto-inheritance into markdown or code-defined agents that enable `autoInheritTools`. Defaults to `false` (safe-by-default) — plugin authors must explicitly opt a tool in if they consider it safe enough to appear in every agent's tool record without an explicit `tools:` declaration. Destructive or privilege-sensitive tools should leave this unset so that they only reach agents that wire them explicitly (via `tools:` object/function form, markdown `plugin:NAME` entries in the unified `tools:` list, or `plugins.<name>.toolkit({ only: [...] })`).
+
+***
+
+### description[​](#description "Direct link to description")
+
+```ts
+description: string;
+
+```
+
+***
+
+### execute()[​](#execute "Direct link to execute()")
+
+```ts
+execute: (args: output<S>, signal?: AbortSignal) => unknown;
+
+```
+
+Callback the agents plugin invokes after Zod validation succeeds.
+
+Named `execute` to match the public `tool({ execute })` form — both the agent-author surface and the plugin-author surface now spell their callback the same way. `args` is the inferred Zod output (so `T extends z.ZodType` flows through and `args` is fully typed). `signal` is the per-run AbortSignal: forward it to any awaited I/O so cancellation actually unwinds the call (analytics and lakebase both do this).
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `args`    | `output`<`S`> |
+| `signal?` | `AbortSignal` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`unknown`
+
+***
+
+### schema[​](#schema "Direct link to schema")
+
+```ts
+schema: S;
+
+```

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

@@ -0,0 +1,38 @@
+# Interface: ToolProvider
+
+## Methods[​](#methods "Direct link to Methods")
+
+### executeAgentTool()[​](#executeagenttool "Direct link to executeAgentTool()")
+
+```ts
+executeAgentTool(
+   name: string, 
+   args: unknown, 
+signal?: AbortSignal): Promise<unknown>;
+
+```
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `name`    | `string`      |
+| `args`    | `unknown`     |
+| `signal?` | `AbortSignal` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`unknown`>
+
+***
+
+### getAgentTools()[​](#getagenttools "Direct link to getAgentTools()")
+
+```ts
+getAgentTools(): AgentToolDefinition[];
+
+```
+
+#### Returns[​](#returns-1 "Direct link to Returns")
+
+[`AgentToolDefinition`](./docs/api/appkit/Interface.AgentToolDefinition.md)\[]

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

@@ -0,0 +1,59 @@
+# Interface: ToolkitEntry
+
+A tool reference produced by a plugin's `.toolkit()` call. The agents plugin recognizes the `__toolkitRef` brand and dispatches tool invocations through `PluginContext.executeTool(req, pluginName, localName, ...)`, preserving OBO (asUser) and telemetry spans.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### \_\_toolkitRef[​](#__toolkitref "Direct link to __toolkitRef")
+
+```ts
+readonly __toolkitRef: true;
+
+```
+
+***
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+***
+
+### autoInheritable?[​](#autoinheritable "Direct link to autoInheritable?")
+
+```ts
+optional autoInheritable: boolean;
+
+```
+
+Whether this tool is eligible for `autoInheritTools` spreading. Mirrors [ToolEntry.autoInheritable](./docs/api/appkit/Interface.ToolEntry.md#autoinheritable) from the source registry so the agents plugin can filter auto-inherited tools without re-walking the provider's internal registry.
+
+***
+
+### def[​](#def "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+***
+
+### localName[​](#localname "Direct link to localName")
+
+```ts
+localName: string;
+
+```
+
+***
+
+### pluginName[​](#pluginname "Direct link to pluginName")
+
+```ts
+pluginName: string;
+
+```

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

@@ -0,0 +1,45 @@
+# Interface: ToolkitOptions
+
+## Properties[​](#properties "Direct link to Properties")
+
+### except?[​](#except "Direct link to except?")
+
+```ts
+optional except: string[];
+
+```
+
+Exclude tools whose local name matches one of these.
+
+***
+
+### only?[​](#only "Direct link to only?")
+
+```ts
+optional only: string[];
+
+```
+
+Only include tools whose local name matches one of these.
+
+***
+
+### prefix?[​](#prefix "Direct link to prefix?")
+
+```ts
+optional prefix: string;
+
+```
+
+Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`.
+
+***
+
+### rename?[​](#rename "Direct link to rename?")
+
+```ts
+optional rename: Record<string, string>;
+
+```
+
+Remap specific local names to different keys (applied after prefix).