@databricks/appkit 0.81.0 → 0.82.0

package/docs/development/templates.md

@@ -14,17 +14,18 @@ Files named with a `_` prefix are renamed to `.` prefix (e.g. `_gitignore` → `
 
 ### Template variables[​](#template-variables "Direct link to Template variables")
 
-| Variable          | Description                                                                  |
-| ----------------- | ---------------------------------------------------------------------------- |
-| `.projectName`    | Project name from `--name` or interactive prompt                             |
-| `.workspaceHost`  | Databricks workspace URL                                                     |
-| `.profile`        | Databricks CLI profile name (empty if using host-based auth)                 |
-| `.appDescription` | App description                                                              |
-| `.plugins.<name>` | Non-nil for each selected plugin, enabling conditionals                      |
-| `.dotEnv.content` | Generated `.env` content from plugin resources                               |
-| `.dotEnv.example` | Generated `.env.example` content with placeholders                           |
-| `.bundle.*`       | Generated `databricks.yml` sections (variables, resources, target variables) |
-| `.appEnv`         | Generated `app.yaml` env entries                                             |
+| Variable          | Description                                                                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `.projectName`    | Project name from `--name` or interactive prompt                                                                                          |
+| `.workspaceHost`  | Databricks workspace URL                                                                                                                  |
+| `.profile`        | Databricks CLI profile name (empty if using host-based auth)                                                                              |
+| `.appDescription` | App description                                                                                                                           |
+| `.packageManager` | Selected package manager (`npm` or `pnpm`). Use `{{or .packageManager "pnpm"}}` to default to pnpm when an older CLI omits this variable. |
+| `.plugins.<name>` | Non-nil for each selected plugin, enabling conditionals                                                                                   |
+| `.dotEnv.content` | Generated `.env` content from plugin resources                                                                                            |
+| `.dotEnv.example` | Generated `.env.example` content with placeholders                                                                                        |
+| `.bundle.*`       | Generated `databricks.yml` sections (variables, resources, target variables)                                                              |
+| `.appEnv`         | Generated `app.yaml` env entries                                                                                                          |
 
 ### Conditional content[​](#conditional-content "Direct link to Conditional content")
 

package/docs/plugins/agents.md

@@ -14,6 +14,8 @@ Streaming-capable serving endpoints only
 
 The agents plugin drives the LLM over Server-Sent Events. Foundation Model APIs (Claude, Llama, GPT, etc.) and other chat-style endpoints support streaming and work out of the box. Custom model endpoints that return a single JSON response (e.g. typical `sklearn` or MLflow `pyfunc` deployments) do **not** stream — pointing an agent at one will fail with "Response body is null — streaming not supported" on the first turn. If you list a serving endpoint in `apps init`, pick one whose model implements the chat-completions streaming protocol; the agents plugin reads its name from `DATABRICKS_SERVING_ENDPOINT_NAME` whenever an agent doesn't pin `model:` itself.
 
+`fromModelServing` (the serving-endpoint adapter) uses the OpenAI **chat-completions** streaming protocol, so it drives chat-completions serving endpoints (task type `agent/*/chat`) and Databricks foundation models. An endpoint on the Responses API (task type `agent/*/responses`, e.g. a `ResponsesAgent`) rejects a chat-completions request, so `fromModelServing` can't drive it.
+
 For the non-streaming path against a custom endpoint, use the `serving` plugin's `/invoke` route with `useServingInvoke` instead.
 
 Or skip serving-endpoint setup entirely with the managed [Supervisor API adapter](#managed-agents-the-supervisor-api-adapter) (beta).
@@ -163,7 +165,7 @@ Auto-inherit is **off for both origins by default** — a markdown or code agent
 
 Deprecated: the `agents({ agents: { ... } })` map
 
-Passing a hand-built agent map still works and is honored for backward compatibility, but it emits a one-time deprecation warning and will be removed in a future minor. It restates each agent's id (once in `createAgent`, once as the map key); discovery from `server/agents/` removes both the map and the restatement. Migrate by moving each `createAgent(...)` into its own `server/agents/<id>/agent.ts` (default or single named export) and dropping the map. If a discovered agent and a map entry share an id, discovery wins and the map entry is ignored (with a one-time warning). (Inline sub-agents — `createAgent({ agents: { ... } })` on a definition — are unaffected; only the plugin-level map is deprecated.)
+Passing a hand-built agent map still works and is honored for backward compatibility, but it is deprecated as of 0.64.0: it emits a one-time deprecation warning and will be removed in a future minor. It restates each agent's id (once in `createAgent`, once as the map key); discovery from `server/agents/` removes both the map and the restatement. Migrate by moving each `createAgent(...)` into its own `server/agents/<id>/agent.ts` (default or single named export) and dropping the map. If a discovered agent and a map entry share an id, discovery wins and the map entry is ignored (with a one-time warning). (Inline sub-agents — `createAgent({ agents: { ... } })` on a definition — are unaffected; only the plugin-level map is deprecated.)
 
 Some examples further down still pass agents inline via this map for snippet brevity — in a real app each of those `createAgent(...)` definitions lives in its own `server/agents/<id>/agent.ts` and needs no map.
 

package/docs/plugins/execution-context.md

@@ -30,6 +30,22 @@ router.post("/system/data", async (req, res) => {
 
 ```
 
+## Which built-in surfaces run OBO vs service principal[​](#which-built-in-surfaces-run-obo-vs-service-principal "Direct link to Which built-in surfaces run OBO vs service principal")
+
+The default is the **service principal**: an operation runs on behalf of the user only when it goes through `asUser(req)`, which needs the forwarded user token. There is no global "OBO everywhere" mode, so identity is decided per surface:
+
+| Surface                                                     | Runs as               | Why                                                                                                                |
+| ----------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Genie routes                                                | signed-in user (OBO)  | the built-in route calls `asUser(req)` automatically                                                               |
+| Files / Analytics ops via `asUser(req)`                     | signed-in user (OBO)  | service principal by default; OBO only when you wrap the call in `asUser(req)`                                     |
+| Agents plugin `/chat` — the model (LLM) call                | app service principal | the chat route does not call `asUser`, and the model adapter is built at startup with the service-principal client |
+| Agents plugin — plugin-toolkit tool calls (`plugin:<name>`) | signed-in user (OBO)  | dispatched through `asUser(req)` per call                                                                          |
+| Agents plugin — hand-rolled `tool({ execute })`             | app service principal | receives only tool arguments, no `req`, so it can't opt into OBO                                                   |
+| Standalone `runAgent` (no HTTP request)                     | app service principal | no request context, so neither the model nor any tool runs OBO                                                     |
+| Serving plugin (deprecated) routes                          | signed-in user (OBO)  | the built-in route calls `asUser(req)`; prefer the agents plugin                                                   |
+
+So an agent's **model inference runs as the service principal**; only the plugin tools it calls over the built-in HTTP routes run on behalf of the user. See the [agents plugin](./docs/plugins/agents.md) for the tool-level detail.
+
 ## Context helper functions[​](#context-helper-functions "Direct link to Context helper functions")
 
 Exported from `@databricks/appkit`:

package/docs/plugins/model-serving.md

@@ -1,5 +1,9 @@
 # Model Serving plugin
 
+Deprecated in favor of the agents plugin
+
+`serving()` (`useServingStream` / `useServingInvoke`) is deprecated as of AppKit 0.77.0; for chat and streaming, use the [agents plugin](./docs/plugins/agents.md) (`DatabricksAdapter.fromModelServing` + `useAgentChat`). The agents plugin drives only streaming chat-completions endpoints, so non-streaming custom model endpoints (`sklearn`/`pyfunc`) have no agents equivalent; `/invoke` still serves them until the plugin is removed.
+
 Provides an authenticated proxy to [Databricks Model Serving](https://docs.databricks.com/aws/en/machine-learning/model-serving) endpoints, with invoke and streaming support.
 
 **Key features:**

package/llms.txt

@@ -55,7 +55,7 @@ npx @databricks/appkit docs <query>
 - [Jobs plugin](./docs/plugins/jobs.md): Trigger and monitor Databricks Lakeflow Jobs from your AppKit application.
 - [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
 - [Plugin manifest](./docs/plugins/manifest.md): Every plugin ships a manifest.json next to its source code. The manifest declares plugin metadata, the Databricks resources the plugin needs, and any structured rules a scaffolding agent must honor when running databricks apps init. It is consumed at three stages:
-- [Model Serving plugin](./docs/plugins/model-serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
+- [Model Serving plugin](./docs/plugins/model-serving.md): serving() (useServingStream / useServingInvoke) is deprecated as of AppKit 0.77.0; for chat and streaming, use the agents plugin (DatabricksAdapter.fromModelServing + useAgentChat). The agents plugin drives only streaming chat-completions endpoints, so non-streaming custom model endpoints (sklearn/pyfunc) have no agents equivalent; /invoke still serves them until the plugin is removed.
 - [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.

package/package.json

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