refactor(appkit): retire toPluginWithInstance; consolidate on fromPlugin + fix schema/routing bugs

apps/dev-playground/config/agents/assistant.md

@@ -1,7 +1,6 @@
 ---
-
-## endpoint: databricks-claude-sonnet-4-5
-
+endpoint: databricks-claude-sonnet-4-5
 default: true
+---
 
-You are a helpful data assistant. Use the available tools to query data and help users with their analysis.
+You are a helpful data assistant. Use the available tools to query data and help users with their analysis.

docs/docs/api/appkit/Class.Plugin.md

@@ -252,6 +252,42 @@ AuthenticationError if user token is not available in request headers (productio
 
 ***
 
+### attachContext()
+
+```ts
+attachContext(deps: {
+  context?: unknown;
+  telemetryConfig?: TelemetryOptions;
+}): void;
+```
+
+Binds runtime dependencies (telemetry provider, cache, plugin context) to
+this plugin. Called by `AppKit._createApp` after construction and before
+`setup()`. Idempotent: safe to call if the constructor already bound them
+eagerly. Kept separate so factories can eagerly construct plugin instances
+without running this before `TelemetryManager.initialize()` /
+`CacheManager.getInstance()` have run.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `deps` | \{ `context?`: `unknown`; `telemetryConfig?`: `TelemetryOptions`; \} |
+| `deps.context?` | `unknown` |
+| `deps.telemetryConfig?` | `TelemetryOptions` |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+BasePlugin.attachContext
+```
+
+***
+
 ### clientConfig()
 
 ```ts

docs/docs/api/appkit/Function.createAgent.md

@@ -1,52 +1,35 @@
 # Function: createAgent()
 
 ```ts
-function createAgent(config: CreateAgentConfig): Promise<AgentHandle>;
+function createAgent(def: AgentDefinition): AgentDefinition;
 ```
 
-Creates an agent-powered app with batteries included.
+Pure factory for agent definitions. Returns the passed-in definition after
+cycle-detecting the sub-agent graph. Accepts the full `AgentDefinition` shape
+and is safe to call at module top-level.
 
-Wraps `createApp` with `server()` and `agent()` pre-configured.
-Automatically starts an HTTP server with agent chat routes.
-
-For apps that need custom routes or manual server control,
-use `createApp` with `server()` and `agent()` directly.
+The returned value is a plain `AgentDefinition` — no adapter construction,
+no side effects. Register it with `agents({ agents: { name: def } })` or run
+it standalone via `runAgent(def, input)`.
 
 ## Parameters
 
 | Parameter | Type |
 | ------ | ------ |
-| `config` | [`CreateAgentConfig`](Interface.CreateAgentConfig.md) |
+| `def` | [`AgentDefinition`](Interface.AgentDefinition.md) |
 
 ## Returns
 
-`Promise`\<[`AgentHandle`](Interface.AgentHandle.md)\>
-
-## Examples
+[`AgentDefinition`](Interface.AgentDefinition.md)
 
-```ts
-import { createAgent, analytics } from "@databricks/appkit";
-import { DatabricksAdapter } from "@databricks/appkit/agents/databricks";
-
-createAgent({
-  plugins: [analytics()],
-  adapter: DatabricksAdapter.fromServingEndpoint({
-    workspaceClient: new WorkspaceClient({}),
-    endpointName: "databricks-claude-sonnet-4-5",
-    systemPrompt: "You are a data assistant...",
-  }),
-}).then(agent => {
-  console.log("Tools:", agent.getTools());
-});
-```
+## Example
 
 ```ts
-createAgent({
-  plugins: [analytics(), files()],
-  agents: {
-    assistant: DatabricksAdapter.fromServingEndpoint({ ... }),
-    autocomplete: DatabricksAdapter.fromServingEndpoint({ ... }),
+const support = createAgent({
+  instructions: "You help customers.",
+  model: "databricks-claude-sonnet-4-5",
+  tools: {
+    get_weather: tool({ ... }),
   },
-  defaultAgent: "assistant",
 });
 ```

docs/docs/api/appkit/Function.fromPlugin.md

@@ -0,0 +1,50 @@
+# Function: fromPlugin()
+
+```ts
+function fromPlugin<F>(factory: F, opts?: ToolkitOptions): FromPluginSpread;
+```
+
+Reference a plugin's tools inside an `AgentDefinition.tools` record without
+naming the plugin instance. The returned spread-friendly object carries a
+symbol-keyed marker that the agents plugin resolves against registered
+`ToolProvider`s at setup time.
+
+The factory argument must come from `toPlugin` (or any function that
+carries a `pluginName` field). `fromPlugin` reads `factory.pluginName`
+synchronously — it does not construct an instance.
+
+If the referenced plugin is also registered in `createApp({ plugins })`, the
+same runtime instance is used for dispatch. If the plugin is missing,
+`AgentsPlugin.setup()` throws with a clear `Available: …` listing.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `F` *extends* `NamedPluginFactory` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `factory` | `F` | A plugin factory produced by `toPlugin`. Must expose a `pluginName` field. |
+| `opts?` | [`ToolkitOptions`](Interface.ToolkitOptions.md) | Optional toolkit scoping — `prefix`, `only`, `except`, `rename`. Same shape as the `.toolkit()` method. |
+
+## Returns
+
+`FromPluginSpread`
+
+## Example
+
+```ts
+import { analytics, createAgent, files, fromPlugin, tool } from "@databricks/appkit";
+
+const support = createAgent({
+  instructions: "You help customers.",
+  tools: {
+    ...fromPlugin(analytics),
+    ...fromPlugin(files, { only: ["uploads.read"] }),
+    get_weather: tool({ ... }),
+  },
+});
+```

docs/docs/api/appkit/Function.isFromPluginMarker.md

@@ -0,0 +1,17 @@
+# Function: isFromPluginMarker()
+
+```ts
+function isFromPluginMarker(value: unknown): value is FromPluginMarker;
+```
+
+Type guard for [FromPluginMarker](Interface.FromPluginMarker.md).
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `unknown` |
+
+## Returns
+
+`value is FromPluginMarker`

docs/docs/api/appkit/Function.isToolkitEntry.md

@@ -0,0 +1,18 @@
+# Function: isToolkitEntry()
+
+```ts
+function isToolkitEntry(value: unknown): value is ToolkitEntry;
+```
+
+Type guard for `ToolkitEntry` — used by the agents plugin to differentiate
+toolkit references from inline tools in a mixed `tools` record.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `unknown` |
+
+## Returns
+
+`value is ToolkitEntry`

docs/docs/api/appkit/Function.loadAgentFromFile.md

@@ -0,0 +1,19 @@
+# Function: loadAgentFromFile()
+
+```ts
+function loadAgentFromFile(filePath: string, ctx: LoadContext): Promise<AgentDefinition>;
+```
+
+Loads a single markdown agent file and resolves its frontmatter against
+registered plugin toolkits + ambient tool library.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `filePath` | `string` |
+| `ctx` | `LoadContext` |
+
+## Returns
+
+`Promise`\<[`AgentDefinition`](Interface.AgentDefinition.md)\>

docs/docs/api/appkit/Function.loadAgentsFromDir.md

@@ -0,0 +1,20 @@
+# Function: loadAgentsFromDir()
+
+```ts
+function loadAgentsFromDir(dir: string, ctx: LoadContext): Promise<LoadResult>;
+```
+
+Scans a directory for `*.md` files and produces an `AgentDefinition` record
+keyed by file-stem. Throws on frontmatter errors or unresolved references.
+Returns an empty map if the directory does not exist.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `dir` | `string` |
+| `ctx` | `LoadContext` |
+
+## Returns
+
+`Promise`\<`LoadResult`\>

docs/docs/api/appkit/Function.runAgent.md

@@ -0,0 +1,29 @@
+# Function: runAgent()
+
+```ts
+function runAgent(def: AgentDefinition, input: RunAgentInput): Promise<RunAgentResult>;
+```
+
+Standalone agent execution without `createApp`. Resolves the adapter, binds
+inline tools, and drives the adapter's `run()` loop to completion.
+
+Limitations vs. running through the agents() plugin:
+- No OBO: there is no HTTP request, so plugin tools run as the service
+  principal (when they work at all).
+- Hosted tools (MCP) are not supported — they require a live MCP client
+  that only exists inside the agents plugin.
+- Sub-agents (`agents: { ... }` on the def) are executed as nested
+  `runAgent` calls with no shared thread state.
+- Plugin tools (`fromPlugin` markers or `ToolkitEntry` spreads) require
+  passing `plugins: [...]` via `RunAgentInput`.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `def` | [`AgentDefinition`](Interface.AgentDefinition.md) |
+| `input` | [`RunAgentInput`](Interface.RunAgentInput.md) |
+
+## Returns
+
+`Promise`\<[`RunAgentResult`](Interface.RunAgentResult.md)\>

docs/docs/api/appkit/Interface.AgentDefinition.md

@@ -0,0 +1,82 @@
+# Interface: AgentDefinition
+
+## Properties
+
+### agents?
+
+```ts
+optional agents: Record<string, AgentDefinition>;
+```
+
+Sub-agents, exposed as `agent-<key>` tools on this agent.
+
+***
+
+### baseSystemPrompt?
+
+```ts
+optional baseSystemPrompt: BaseSystemPromptOption;
+```
+
+Override the plugin's baseSystemPrompt for this agent only.
+
+***
+
+### instructions
+
+```ts
+instructions: string;
+```
+
+System prompt body. For markdown-loaded agents this is the file body.
+
+***
+
+### maxSteps?
+
+```ts
+optional maxSteps: number;
+```
+
+***
+
+### maxTokens?
+
+```ts
+optional maxTokens: number;
+```
+
+***
+
+### model?
+
+```ts
+optional model: 
+  | string
+  | AgentAdapter
+| Promise<AgentAdapter>;
+```
+
+Model adapter (or endpoint-name string sugar for
+`DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —
+falls back to the plugin's `defaultModel`.
+
+***
+
+### name?
+
+```ts
+optional name: string;
+```
+
+Filled in from the enclosing key when used in `agents: { foo: def }`.
+
+***
+
+### tools?
+
+```ts
+optional tools: AgentTools;
+```
+
+Per-agent tool record. Key is the LLM-visible tool-call name.