docs: beta agents banner, template stability, and unified typedoc entry

MarioCadenas · MarioCadenas · commit c43aacfb2a33 · 2026-05-07T11:46:52.000+02:00
- Document agents as beta in docs and set stability in app template manifest
- Point Docusaurus Typedoc at typedoc.entry.ts so stable + beta APIs publish
  together (fixes agent symbol pages being dropped from index-only builds)
- Regenerate api/appkit index and sidebar; knip-ignore docs-only entry file

Signed-off-by: MarioCadenas &lt;MarioCadenas@users.noreply.github.com&gt;
diff --git a/docs/docs/api/appkit/Interface.AgentsPluginConfig.md b/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
@@ -60,7 +60,9 @@ Milliseconds to wait before auto-denying. Default: 60_000.
 ### autoInheritTools?
 
 ```ts
-optional autoInheritTools: boolean | AutoInheritToolsConfig;
+optional autoInheritTools: 
+  | boolean
+  | AutoInheritToolsConfig;
 ```
 
 Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand.
diff --git a/docs/docs/api/appkit/Interface.AutoInheritToolsConfig.md b/docs/docs/api/appkit/Interface.AutoInheritToolsConfig.md
@@ -0,0 +1,30 @@
+# 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:`, `toolkits:`, or `fromPlugin`.
+
+Defaults are `false` for both origins (safe-by-default): developers must
+consciously opt an origin in to any auto-inherit behaviour.
+
+## Properties
+
+### code?
+
+```ts
+optional code: boolean;
+```
+
+Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`.
+
+***
+
+### file?
+
+```ts
+optional file: boolean;
+```
+
+Default for agents loaded from markdown files. Default: `false`.
diff --git a/docs/docs/api/appkit/Interface.BasePluginConfig.md b/docs/docs/api/appkit/Interface.BasePluginConfig.md
@@ -4,8 +4,8 @@ Base configuration interface for AppKit plugins
 
 ## Extended by
 
-- [`AgentsPluginConfig`](Interface.AgentsPluginConfig.md)
 - [`IJobsConfig`](Interface.IJobsConfig.md)
+- [`AgentsPluginConfig`](Interface.AgentsPluginConfig.md)
 
 ## Indexable
 
diff --git a/docs/docs/api/appkit/Interface.LakebasePoolConfig.md b/docs/docs/api/appkit/Interface.LakebasePoolConfig.md
@@ -76,7 +76,7 @@ const pool = createLakebasePool({
 ### sslMode?
 
 ```ts
-optional sslMode: "require" | "disable" | "prefer";
+optional sslMode: "disable" | "require" | "prefer";
 ```
 
 SSL mode for the connection (convenience helper)
diff --git a/docs/docs/api/appkit/Interface.RegisteredAgent.md b/docs/docs/api/appkit/Interface.RegisteredAgent.md
@@ -0,0 +1,67 @@
+# Interface: RegisteredAgent
+
+## Properties
+
+### adapter
+
+```ts
+adapter: AgentAdapter;
+```
+
+***
+
+### baseSystemPrompt?
+
+```ts
+optional baseSystemPrompt: BaseSystemPromptOption;
+```
+
+***
+
+### ephemeral?
+
+```ts
+optional ephemeral: boolean;
+```
+
+Mirrors `AgentDefinition.ephemeral` — skip thread persistence.
+
+***
+
+### instructions
+
+```ts
+instructions: string;
+```
+
+***
+
+### maxSteps?
+
+```ts
+optional maxSteps: number;
+```
+
+***
+
+### maxTokens?
+
+```ts
+optional maxTokens: number;
+```
+
+***
+
+### name
+
+```ts
+name: string;
+```
+
+***
+
+### toolIndex
+
+```ts
+toolIndex: Map<string, ResolvedToolEntry>;
+```
diff --git a/docs/docs/api/appkit/Interface.ToolAnnotations.md b/docs/docs/api/appkit/Interface.ToolAnnotations.md
@@ -0,0 +1,55 @@
+# Interface: ToolAnnotations
+
+## Properties
+
+### ~~destructive?~~
+
+```ts
+optional destructive: boolean;
+```
+
+#### 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?
+
+```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?
+
+```ts
+optional idempotent: boolean;
+```
+
+***
+
+### ~~readOnly?~~
+
+```ts
+optional readOnly: boolean;
+```
+
+#### Deprecated
+
+Prefer [effect](#effect). Retained for backward compatibility
+with tools authored against the original flags and for MCP interop.
+
+***
+
+### requiresUserContext?
+
+```ts
+optional requiresUserContext: boolean;
+```
diff --git a/docs/docs/api/appkit/TypeAlias.ResolvedToolEntry.md b/docs/docs/api/appkit/TypeAlias.ResolvedToolEntry.md
@@ -0,0 +1,28 @@
+# Type Alias: ResolvedToolEntry
+
+```ts
+type ResolvedToolEntry = 
+  | {
+  def: AgentToolDefinition;
+  localName: string;
+  pluginName: string;
+  source: "toolkit";
+}
+  | {
+  def: AgentToolDefinition;
+  functionTool: FunctionTool;
+  source: "function";
+}
+  | {
+  def: AgentToolDefinition;
+  mcpToolName: string;
+  source: "mcp";
+}
+  | {
+  agentName: string;
+  def: AgentToolDefinition;
+  source: "subagent";
+};
+```
+
+Internal tool-index entry after a tool record has been resolved to a dispatchable form.
diff --git a/docs/docs/api/appkit/index.md b/docs/docs/api/appkit/index.md
@@ -1,7 +1,7 @@
 # @databricks/appkit
 
-Core library for building Databricks applications with type-safe SQL queries,
-plugin architecture, and React integration.
+Documentation merge entry for Typedoc — combines the stable `@databricks/appkit`
+surface with `@databricks/appkit/beta`. Not meant for application imports.
 
 ## Enumerations
 
@@ -37,6 +37,7 @@ plugin architecture, and React integration.
 | [AgentRunContext](Interface.AgentRunContext.md) | - |
 | [AgentsPluginConfig](Interface.AgentsPluginConfig.md) | Base configuration interface for AppKit plugins |
 | [AgentToolDefinition](Interface.AgentToolDefinition.md) | - |
+| [AutoInheritToolsConfig](Interface.AutoInheritToolsConfig.md) | 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:`, `toolkits:`, or `fromPlugin`. |
 | [BasePluginConfig](Interface.BasePluginConfig.md) | Base configuration interface for AppKit plugins |
 | [CacheConfig](Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
 | [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
@@ -55,6 +56,7 @@ plugin architecture, and React integration.
 | [Message](Interface.Message.md) | - |
 | [PluginManifest](Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types. |
 | [PromptContext](Interface.PromptContext.md) | Context passed to `baseSystemPrompt` callbacks. |
+| [RegisteredAgent](Interface.RegisteredAgent.md) | - |
 | [RequestedClaims](Interface.RequestedClaims.md) | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables |
 | [RequestedResource](Interface.RequestedResource.md) | Resource to request permissions for in Unity Catalog |
 | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
@@ -68,6 +70,7 @@ plugin architecture, and React integration.
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
 | [Thread](Interface.Thread.md) | - |
 | [ThreadStore](Interface.ThreadStore.md) | - |
+| [ToolAnnotations](Interface.ToolAnnotations.md) | - |
 | [ToolConfig](Interface.ToolConfig.md) | - |
 | [ToolkitEntry](Interface.ToolkitEntry.md) | 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. |
 | [ToolkitOptions](Interface.ToolkitOptions.md) | - |
@@ -91,6 +94,7 @@ plugin architecture, and React integration.
 | [JobHandle](TypeAlias.JobHandle.md) | Job handle returned by `appkit.jobs("etl")`. Supports OBO access via `.asUser(req)`. |
 | [JobsExport](TypeAlias.JobsExport.md) | Public API shape of the jobs plugin. Callable to select a job by key. |
 | [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
+| [ResolvedToolEntry](TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
 | [ServingFactory](TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. |
 | [ToPlugin](TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
diff --git a/docs/docs/api/appkit/typedoc-sidebar.ts b/docs/docs/api/appkit/typedoc-sidebar.ts
@@ -117,6 +117,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.AgentToolDefinition",
           label: "AgentToolDefinition"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.AutoInheritToolsConfig",
+          label: "AutoInheritToolsConfig"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.BasePluginConfig",
@@ -207,6 +212,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.PromptContext",
           label: "PromptContext"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.RegisteredAgent",
+          label: "RegisteredAgent"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.RequestedClaims",
@@ -272,6 +282,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.ThreadStore",
           label: "ThreadStore"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.ToolAnnotations",
+          label: "ToolAnnotations"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.ToolConfig",
@@ -368,6 +383,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.PluginData",
           label: "PluginData"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.ResolvedToolEntry",
+          label: "ResolvedToolEntry"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.ResourcePermission",
diff --git a/docs/docs/plugins/agents.md b/docs/docs/plugins/agents.md
@@ -1,5 +1,11 @@
 # Agents
 
+<!-- AUTO-GENERATED: stability-banner-start -->
+:::warning Beta plugin
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./stability.md).
+:::
+<!-- AUTO-GENERATED: stability-banner-end -->
+
 The `agents` plugin turns a Databricks AppKit app into an AI-agent host. It loads agent definitions from markdown on disk (one folder per agent: `config/agents/<id>/agent.md`), from TypeScript (`createAgent(def)`), or both, and exposes them at `POST /invocations` alongside routes for chat, thread management, and cancellation.
 
 This page covers the full lifecycle. For the hand-written primitives (`tool()`, `mcpServer()`), see [tools](./server.md).
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -119,7 +119,7 @@ const config: Config = {
       "docusaurus-plugin-typedoc",
       {
         id: "appkit",
-        entryPoints: ["../packages/appkit/src/index.ts"],
+        entryPoints: ["../packages/appkit/src/typedoc.entry.ts"],
         tsconfig: "../packages/appkit/tsconfig.json",
         out: "docs/api/appkit",
         gitRevision: "main",
diff --git a/knip.json b/knip.json
@@ -24,6 +24,7 @@
     "packages/appkit/src/core/agent/from-plugin.ts",
     "packages/appkit/src/core/agent/load-agents.ts",
     "packages/appkit/src/connectors/mcp/index.ts",
+    "packages/appkit/src/typedoc.entry.ts",
     "template/**",
     "tools/**",
     "docs/**",
diff --git a/packages/appkit/src/typedoc.entry.ts b/packages/appkit/src/typedoc.entry.ts
@@ -0,0 +1,9 @@
+/**
+ * Documentation merge entry for Typedoc — combines the stable `@databricks/appkit`
+ * surface with `@databricks/appkit/beta`. Not meant for application imports.
+ *
+ * @packageDocumentation
+ */
+
+export * from "./beta";
+export * from "./index";
diff --git a/template/appkit.plugins.json b/template/appkit.plugins.json
@@ -24,7 +24,8 @@
             }
           }
         ]
-      }
+      },
+      "stability": "beta"
     },
     "analytics": {
       "name": "analytics",
