@databricks/appkit-ui 0.32.0 → 0.33.0

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

@@ -0,0 +1,27 @@
+# Interface: AutoInheritToolsConfig
+
+Auto-inherit configuration. When enabled for a given agent origin, agents with no explicit `tools:` declaration receive every registered ToolProvider plugin tool whose author marked `autoInheritable: true`. Tools without that flag — destructive, state-mutating, or privilege-sensitive — never spread automatically and must be wired via `tools:` (object or function form in code, `plugin:NAME` entries in markdown frontmatter).
+
+Defaults are `false` for both origins (safe-by-default): developers must consciously opt an origin in to any auto-inherit behaviour.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### code?[​](#code "Direct link to code?")
+
+```ts
+optional code: boolean;
+
+```
+
+Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`.
+
+***
+
+### file?[​](#file "Direct link to file?")
+
+```ts
+optional file: boolean;
+
+```
+
+Default for agents loaded from markdown files. Default: `false`.

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

@@ -4,6 +4,7 @@ Base configuration interface for AppKit plugins
 
 ## Extended by[​](#extended-by "Direct link to Extended by")
 
+* [`AgentsPluginConfig`](./docs/api/appkit/Interface.AgentsPluginConfig.md)
 * [`IJobsConfig`](./docs/api/appkit/Interface.IJobsConfig.md)
 
 ## Indexable[​](#indexable "Direct link to Indexable")

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

@@ -0,0 +1,80 @@
+# Interface: FunctionTool
+
+## Properties[​](#properties "Direct link to Properties")
+
+### annotations?[​](#annotations "Direct link to annotations?")
+
+```ts
+optional annotations: ToolAnnotations;
+
+```
+
+Behavioural hints that drive the agents plugin's approval gate and the client's approval-card styling. Prefer setting `effect` (one of `"read" | "write" | "update" | "destructive"`) — any mutating value forces HITL approval before `execute()` runs. Legacy `destructive: true` is still honoured. Must be preserved through [functionToolToDefinition](./docs/api/appkit/Function.functionToolToDefinition.md) so the plugin sees them when building agent tool indexes.
+
+***
+
+### description?[​](#description "Direct link to description?")
+
+```ts
+optional description: string | null;
+
+```
+
+***
+
+### execute()[​](#execute "Direct link to execute()")
+
+```ts
+execute: (args: Record<string, unknown>) => unknown;
+
+```
+
+Returns any shape; downstream `normalizeToolResult` serializes to a string before handing the value to the LLM.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `args`    | `Record`<`string`, `unknown`> |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`unknown`
+
+***
+
+### name?[​](#name "Direct link to name?")
+
+```ts
+optional name: string;
+
+```
+
+Optional. When this tool is placed in a keyed record (`tools: { my_tool: ... }` or the function form), the agents plugin overrides this with the record key at index-build time. Only set it explicitly when constructing a `FunctionTool` outside any keyed-record context.
+
+***
+
+### parameters?[​](#parameters-1 "Direct link to parameters?")
+
+```ts
+optional parameters: Record<string, unknown> | null;
+
+```
+
+***
+
+### strict?[​](#strict "Direct link to strict?")
+
+```ts
+optional strict: boolean | null;
+
+```
+
+***
+
+### type[​](#type "Direct link to type")
+
+```ts
+type: "function";
+
+```

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

@@ -0,0 +1,38 @@
+# Interface: McpConnectAllResult
+
+Per-endpoint outcome of [AppKitMcpClient.connectAll](./docs/api/appkit/Class.AppKitMcpClient.md#connectall). Callers (the agents plugin in particular) use the split to warn at startup when some MCP servers are unreachable without aborting boot for the rest.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### connected[​](#connected "Direct link to connected")
+
+```ts
+connected: string[];
+
+```
+
+***
+
+### failed[​](#failed "Direct link to failed")
+
+```ts
+failed: {
+  error: Error;
+  name: string;
+}[];
+
+```
+
+#### error[​](#error "Direct link to error")
+
+```ts
+error: Error;
+
+```
+
+#### name[​](#name "Direct link to name")
+
+```ts
+name: string;
+
+```

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

@@ -0,0 +1,55 @@
+# Interface: Message
+
+## Properties[​](#properties "Direct link to Properties")
+
+### content[​](#content "Direct link to content")
+
+```ts
+content: string;
+
+```
+
+***
+
+### createdAt[​](#createdat "Direct link to createdAt")
+
+```ts
+createdAt: Date;
+
+```
+
+***
+
+### id[​](#id "Direct link to id")
+
+```ts
+id: string;
+
+```
+
+***
+
+### role[​](#role "Direct link to role")
+
+```ts
+role: "user" | "assistant" | "system" | "tool";
+
+```
+
+***
+
+### toolCallId?[​](#toolcallid "Direct link to toolCallId?")
+
+```ts
+optional toolCallId: string;
+
+```
+
+***
+
+### toolCalls?[​](#toolcalls "Direct link to toolCalls?")
+
+```ts
+optional toolCalls: ToolCall[];
+
+```

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;
+
+```