@dbx-tools/appkit-mastra 0.9.99 → 0.9.106

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,43 +3,35 @@
3
3
  AppKit plugin and server-side toolkit for hosting Mastra agents inside a
4
4
  Databricks App.
5
5
 
6
- Import this package when an AppKit backend needs an agent service with
7
- Databricks on-behalf-of auth, optional Lakebase-backed memory, Databricks Genie
8
- tools, model selection, chart/data embeds, MLflow feedback, and MCP exposure.
9
- The package mounts the standard Mastra agent stream under the AppKit server, so
10
- clients can use Mastra-compatible chat transports instead of a custom protocol.
11
-
12
- Key features:
13
-
14
- - AppKit plugin lifecycle integration: routes, setup, shutdown, sibling plugin
15
- access, and AppKit request context are handled inside `mastra()`.
16
- - Agent composition: define one or more Mastra agents, give each one local tools,
17
- AppKit plugin toolkits, workspace skills, model defaults, and approval-gated
18
- tools.
19
- - Databricks execution model: tool calls run with the active AppKit OBO client
20
- where available, while storage and background work use service-principal
21
- connections. Set `genieIdentity: "service-principal"` to run the agents'
22
- Databricks calls as the app service principal instead, so callers who can open
23
- the app but are not workspace members can still chat, or `"auto"` to make that
24
- fallback per-request - OBO when the caller forwards a token, service principal
25
- when they cannot.
26
- - Durable conversations: Lakebase-backed Mastra storage provides thread
27
- history, message persistence, and optional vector memory.
28
- - Isolated command execution: auto-created workspaces use Databricks Sandbox by
29
- default, created lazily per attributed user outside the App container.
30
- - Rich data answers: Genie tools, statement fetches, chart preparation, and
31
- embed markers let an agent answer with text plus delayed chart/table payloads.
32
- - Operational surfaces: model-list routes, feedback routes, MCP exposure,
33
- scoped API gating, tracing, and MLflow feedback are bundled with the plugin.
34
-
35
- ## Why Not Just AppKit Agents?
36
-
37
- Native AppKit includes a beta Agents plugin with markdown and TypeScript agent
38
- definitions, AppKit tool-provider integration, streaming chat, thread
39
- management, cancellation, and HITL approval. Use it when you want the AppKit
40
- agent model and do not need a separate agent framework.
41
-
42
- Use this package when you specifically want Mastra inside AppKit:
6
+ The plugin mounts Mastra's streaming routes in an AppKit server and adds
7
+ Databricks authentication, Lakebase-backed memory, Genie tools, model selection,
8
+ chart and table embeds, MLflow feedback, and MCP exposure.
9
+
10
+ ## Quick Start
11
+
12
+ Add an agent and run its command tools in a per-user Databricks Sandbox:
13
+
14
+ ```ts
15
+ import { createApp, server } from "@databricks/appkit";
16
+ import { agents, mastra } from "@dbx-tools/appkit-mastra";
17
+
18
+ const analyst = agents.createAgent({
19
+ instructions: "Answer questions and use Python when analysis requires it.",
20
+ });
21
+
22
+ await createApp({
23
+ plugins: [server(), mastra({ agents: { analyst }, sandbox: "databricks" })],
24
+ });
25
+ ```
26
+
27
+ Add Lakebase, Genie, Analytics, or other AppKit plugins when the agent needs
28
+ durable threads or workspace tools.
29
+
30
+ ## Choose Mastra Or AppKit Agents
31
+
32
+ Native AppKit Agents is the shorter path for AppKit-native agent definitions,
33
+ streaming chat, threads, cancellation, and approvals. Choose this package when
34
+ the application already uses Mastra or needs Mastra-specific capabilities:
43
35
 
44
36
  - Mastra's larger plugin/tool ecosystem, MCP support, memory/storage model,
45
37
  workflow primitives, and `@mastra/client-js` stream shape.
@@ -53,7 +45,7 @@ Use this package when you specifically want Mastra inside AppKit:
53
45
  [`@dbx-tools/model`](../model), instead of binding every agent to a fixed
54
46
  endpoint name.
55
47
 
56
- ## Quick Start
48
+ ## Full App Example
57
49
 
58
50
  ```ts
59
51
  import { analytics, createApp, lakebase, server } from "@databricks/appkit";
@@ -96,7 +88,7 @@ await createApp({
96
88
  });
97
89
  ```
98
90
 
99
- Benefits of importing the package:
91
+ This example provides:
100
92
 
101
93
  - `mastra()` registers a full AppKit plugin named `mastra`.
102
94
  - `agents.createAgent()` keeps agent definitions typed and applies the default
@@ -141,6 +133,10 @@ const approveRefund = agents.createTool({
141
133
  });
142
134
  ```
143
135
 
136
+ Agents are also told to issue independent tool calls together in one turn and
137
+ to keep dependent or conflicting calls sequential. Models that do not support
138
+ parallel tool calls continue through the normal multi-step agent loop.
139
+
144
140
  ## Typed Application Request Context
145
141
 
146
142
  Use Mastra's native `requestContextSchema` for UI selections that should shape a
@@ -341,18 +337,14 @@ export const workspace = new Workspace({
341
337
  });
342
338
  ```
343
339
 
344
- Mastra's native `WorkspaceSkills` owns discovery, indexing, refreshes, and lazy
345
- reads of references, scripts, templates, and assets. dbx-tools does not keep a
346
- second skill catalogue or skill-specific cache.
340
+ Mastra discovers and loads skills from the configured roots. Set
341
+ `workspaceSkills: false` to disable skill search, or pass `{ topK, minScore,
342
+ ttlMs }` to tune it.
347
343
 
348
- When the app registers `filesCache()` from `@dbx-tools/appkit/files-cache`,
349
- default workspaces and workspaces created with `databricksWorkspace()` retain
350
- one filesystem source per user and set of actual mount paths. Page refreshes
351
- and later turns reuse that source, allowing Mastra to retain its native parsed
352
- catalogue while the files cache handles repeated filesystem metadata
353
- operations. Each operation resolves the active request's OBO client, so the
354
- retained source does not retain an old token. Other caller-owned Mastra
355
- workspaces remain unchanged.
344
+ ### Cache Workspace Metadata
345
+
346
+ Register `filesCache()` to reuse Databricks directory metadata across page
347
+ refreshes and later turns:
356
348
 
357
349
  ```ts
358
350
  import { filesCache } from "@dbx-tools/appkit/files-cache";
@@ -362,19 +354,9 @@ await createApp({
362
354
  });
363
355
  ```
364
356
 
365
- The plugin is detected from the AppKit plugin context. If it is not registered,
366
- filesystem caching is disabled. When it is registered, its app-lifetime
367
- `FilesCacheManager` is the single owner of the process-local, user-scoped LRU.
368
- Filesystem values do not use AppKit's `CacheManager`: that cache can write
369
- through to Lakebase, while file reads need a local-only fast path. Existing
370
- Lakebase-backed AppKit caching remains unchanged.
371
-
372
- The default file cache stores `exists`, `readdir`, and `stat` results for every
373
- mounted Databricks path. `readFile` is cached only under configured skill roots,
374
- so ordinary file contents remain live. Directory listings therefore remain
375
- cached. Set `cache: false` on `databricksWorkspace()` to disable this behavior,
376
- `true` to select the defaults explicitly, or provide operation/path filters.
377
- Explicit filters replace the defaults and are ORed:
357
+ The cache is isolated by user and mount path. It stores `exists`, `readdir`, and
358
+ `stat` results for mounted Databricks paths and caches `readFile` only under
359
+ skill roots. Set `cache: false` to disable it or provide filters:
378
360
 
379
361
  ```ts
380
362
  const workspace = workspaces.databricksWorkspace({
@@ -386,17 +368,12 @@ const workspace = workspaces.databricksWorkspace({
386
368
  });
387
369
  ```
388
370
 
389
- Mastra exposes its native skill search and loading tools. Save or update a
390
- skill with the native workspace file tools by writing
391
- `<skill-root>/<name>/SKILL.md`. Set `workspaceSkills: false` to disable the
392
- skill search processor, or pass `{ topK, minScore, ttlMs }` to tune it.
371
+ ### Configure File Approvals
393
372
 
394
- Workspace access policy stays on Mastra's native `Workspace.tools` owner. By
395
- default, mounted files are readable without approval. Write, edit, AST edit,
396
- delete, and mkdir run without approval inside the current user's Databricks
397
- workspace home and under explicit `/tmp` mounts. Mutations elsewhere require
398
- approval. Pass native Mastra tool configuration directly to the workspace
399
- shortcut:
373
+ Workspace tools are enabled and run without approval by default. This applies to
374
+ file mutations and command execution with either Monty or Databricks Sandbox.
375
+ Databricks permissions still decide whether a workspace file operation
376
+ succeeds. Opt into approval for the tools that need it:
400
377
 
401
378
  ```ts
402
379
  import { WORKSPACE_TOOLS } from "@mastra/core/workspace";
@@ -404,78 +381,41 @@ import { WORKSPACE_TOOLS } from "@mastra/core/workspace";
404
381
  const workspace = workspaces.databricksWorkspace({
405
382
  paths: ["~/project"],
406
383
  tools: {
407
- requireApproval: false,
408
384
  [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
409
385
  requireApproval: true,
410
386
  requireReadBeforeWrite: true,
411
387
  },
388
+ [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: {
389
+ requireApproval: true,
390
+ },
412
391
  },
413
392
  });
414
393
  ```
415
394
 
416
- File-tool and sandbox-command policies are independent. Disable
417
- `WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND` when an agent must not bypass file
418
- approvals by writing through shell commands.
419
-
420
- Databricks mounts verify read access with an uncached root status request before
421
- the first cached read can succeed. The first mutation is always sent to
422
- Databricks and marks write access only after it succeeds; failed checks are not
423
- retained. This keeps a retained filesystem source from treating an old cache
424
- entry as proof that the current user can still access the path, without creating
425
- temporary write-probe files.
395
+ Set `enabled: false` on a tool to remove it. File approvals and sandbox commands
396
+ are separate, so gate or disable
397
+ `WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND` when commands must not bypass file
398
+ policies. Cached metadata never grants Databricks access.
426
399
 
427
400
  ## Workspace Sandbox
428
401
 
429
- Auto-created agent workspaces use the Node `@pydantic/monty` runtime by default,
430
- so Python command tools work without a workspace preview or remote API.
431
- Monty's native subprocess worker is preferred because Bun's Linux
432
- `worker_threads` support cannot reliably host the WASM worker. The WASM entry is
433
- loaded only when native import fails. Databricks App staging declares the Linux
434
- native package directly so deployment does not depend on transitive optional
435
- dependency installation. The shared pool starts with one worker and can scale
436
- to `max(4, available processors * 2)` workers per app process.
437
-
438
- Opt into the Beta
439
- [Databricks Sandbox](https://docs.databricks.com/aws/en/compute/serverless/sandbox)
440
- with `sandbox: true`, `sandbox: "databricks"`, or a Databricks options object.
441
- The provider derives a stable opaque sandbox id from the workspace and
442
- attributed user, creates the sandbox lazily on the first command, starts a
443
- stopped sandbox, and waits for runnable state. Commands execute through the
444
- synchronous Sandbox API and return Mastra's normal stdout, stderr, exit,
445
- timeout, and truncation fields. When the Beta is definitively unavailable, its
446
- configured fallback defaults to Monty. Permission, authentication, and
447
- transient network failures remain visible instead of silently changing
448
- providers.
449
-
450
- Enable Databricks Sandbox in the workspace Previews page before selecting it.
451
- The adapter creates its own AppKit client through the normal
452
- environment/profile chain, so a Databricks App uses its service principal even
453
- when the agent turn uses OBO. Databricks Apps user authorization does not
454
- currently expose the Sandbox API scope. Outside Apps, a caller that supplies an
455
- explicit OBO client must request the Sandbox API's `sandbox` scope. The Sandbox
456
- filesystem is separate from Databricks Workspace skill mounts; command code must
457
- copy data explicitly when it needs both.
458
-
459
- Monty is intentionally narrower than Databricks Sandbox: it accepts Python
460
- source directly (or `python3 -c`), runs in crash-isolated subprocess workers,
461
- and exposes no host shell, filesystem, network, environment variables, or
462
- third-party packages. Per-command cancellation kills the isolated worker, and
463
- `maxRetainedBytes` bounds retained stdout/stderr without dropping callback
464
- chunks. Prefer Python source for commands that must work on both providers.
465
-
466
- The default needs no configuration:
402
+ Run command tools in a per-user Beta
403
+ [Databricks Sandbox](https://docs.databricks.com/aws/en/compute/serverless/sandbox):
467
404
 
468
405
  ```ts
469
406
  mastra({
470
- agents: analyst,
407
+ agents: { analyst },
408
+ sandbox: "databricks",
471
409
  });
472
410
  ```
473
411
 
474
- Tune the Databricks lifecycle globally for auto-created workspaces:
412
+ Use `sandbox: true` for the same selection. Pass options to set startup and
413
+ command limits or to fall back to the local Python runtime when the workspace
414
+ does not have the preview:
475
415
 
476
416
  ```ts
477
417
  mastra({
478
- agents: analyst,
418
+ agents: { analyst },
479
419
  sandbox: {
480
420
  inactivityTimeout: "1800s",
481
421
  startupTimeoutMs: 180_000,
@@ -485,6 +425,33 @@ mastra({
485
425
  });
486
426
  ```
487
427
 
428
+ The sandbox is created on the first command and reused for the attributed user.
429
+ Commands return the normal Mastra stdout, stderr, exit, timeout, and truncation
430
+ fields. Authentication, permission, and network failures are returned to the
431
+ caller; only a definitive unavailable-preview response uses the configured
432
+ fallback.
433
+
434
+ Enable Databricks Sandbox in the workspace Previews page before selecting it.
435
+ The adapter creates its own AppKit client through the normal
436
+ environment/profile chain, so a Databricks App uses its service principal even
437
+ when the agent turn uses OBO. Databricks Apps user authorization does not
438
+ currently expose the Sandbox API scope. Outside Apps, a caller that supplies an
439
+ explicit OBO client must request the Sandbox API's `sandbox` scope. The Sandbox
440
+ filesystem is separate from Databricks Workspace skill mounts; command code must
441
+ copy data explicitly when it needs both.
442
+
443
+ Without a `sandbox` option, command tools use the local Monty Python runtime:
444
+
445
+ ```ts
446
+ mastra({
447
+ agents: analyst,
448
+ });
449
+ ```
450
+
451
+ Monty accepts Python source or `python3 -c` and has no host filesystem, network,
452
+ environment variables, shell, or third-party packages. Use Python source when a
453
+ command must work with either provider.
454
+
488
455
  Disable command execution, select Databricks, or provide any Mastra sandbox on
489
456
  one agent:
490
457
 
@@ -500,17 +467,14 @@ const localAgent = agents.createAgent({
500
467
  });
501
468
  ```
502
469
 
503
- An explicit agent `workspace` always wins over plugin-level `sandbox` config, so
504
- providers never run in parallel accidentally. A per-agent workspace resolver
505
- returning `undefined` explicitly disables the workspace for that agent.
470
+ An agent-level workspace overrides the plugin-level sandbox setting. Returning
471
+ `undefined` from a workspace resolver disables the workspace for that agent.
506
472
 
507
473
  ## Remote Skills
508
474
 
509
- Workspace skills above are discovered from files ALREADY in the Databricks
510
- workspace. `remoteSkills` provisions skills from OUTSIDE it at startup - a
511
- GitHub `owner/repo`, a git / GitLab URL, or a direct `SKILL.md` / archive
512
- download URL - so an app can ship with a curated skill set without anyone
513
- hand-uploading `SKILL.md` trees first.
475
+ Use `remoteSkills` to install a curated skill set when the files are not already
476
+ in the Databricks workspace. Sources can be a GitHub `owner/repo`, a git URL, a
477
+ direct `SKILL.md`, or an archive URL.
514
478
 
515
479
  ```ts
516
480
  mastra({
@@ -522,54 +486,29 @@ mastra({
522
486
  });
523
487
  ```
524
488
 
525
- Each source is materialized at boot into an Assistant-style `SKILL.md` tree that
526
- the default workspace then scans, so a provisioned skill behaves exactly like
527
- one that was in the workspace all along. Resolution per source:
528
-
529
- - if the optional `skills` peer dependency is installed, the source is copied
530
- into a staging dir with the `skills` CLI, which understands every source
531
- format the ecosystem does (GitHub shorthand, git URLs, archive URLs);
532
- - otherwise the source URL is fetched directly and its `SKILL.md` written to the
533
- staging dir. A non-URL source (e.g. bare `owner/repo`) without the `skills`
534
- package installed cannot be resolved this way and fails.
535
-
536
- The default destination is the shared Databricks Assistant skills tree
537
- (`/Workspace/.assistant/skills`), so provisioned skills persist across restarts and are picked up by
538
- the built-in Assistant-skills mount. Pass `userEmail` to target that user's
539
- `/Workspace/Users/<email>/.assistant/skills` instead, or `databricksBasePath` for an
540
- explicit tree. When no Databricks client is resolvable at startup, the tree is
541
- written to a local temp dir and handed to Mastra as an extra local skill path
542
- for the current process only.
543
-
544
- The destination is **probed with a real write** before it is used, and falls back
545
- to that local tree when the probe fails. Writing the shared
546
- `/Workspace/.assistant/skills` tree is a workspace-ADMIN action, and a Databricks
547
- App runs as a non-admin service principal, so the common deployment cannot write
548
- it - and the workspace API reports a path the caller may not touch as
549
- `RESOURCE_DOES_NOT_EXIST` rather than a permission error. Only the storage
550
- LOCATION degrades: the same skills are provisioned either way, so a
551
- non-admin app keeps a working agent instead of failing startup. Give the app's
552
- service principal `CAN_MANAGE` on the tree (or point `databricksBasePath` at one
553
- it owns) to get workspace persistence back.
554
-
555
- A source that resolves through neither path fails app startup, so a misconfigured
556
- skill set is caught at boot rather than silently missing. Set `failOnError: false`
557
- (top-level or per-source) to log and skip a bad source instead. Install the
558
- optional peer to enable the richest source formats:
489
+ Each source is copied into an Assistant-style `SKILL.md` tree at startup. Install
490
+ the optional `skills` package for GitHub shorthand, git repositories, and archive
491
+ URLs:
559
492
 
560
493
  ```sh
561
- pnpm add skills
494
+ bun add skills
562
495
  ```
563
496
 
497
+ Without that package, direct `SKILL.md` URLs still work.
498
+
499
+ The default destination is `/Workspace/.assistant/skills`. Set `userEmail` for a
500
+ user-specific Assistant tree or `databricksBasePath` for another location. If
501
+ the app cannot write the selected workspace path, it uses a process-local skill
502
+ tree so the agent can still start. Grant the app service principal access to the
503
+ workspace path when the skills must persist across restarts.
504
+
505
+ A source error fails startup by default. Set `failOnError: false` globally or on
506
+ one source to log and skip it.
507
+
564
508
  ### Refresh policy
565
509
 
566
- Provisioning runs on every app boot, and skill trees change rarely, so each
567
- provisioned tree carries a `.metadata.json` at its root recording when each
568
- source was last downloaded. A source is only re-downloaded once that record is
569
- older than seven days; inside the window the existing tree is reused and no network
570
- call is made. The record travels with the tree rather than living in process
571
- memory, so a container that restarts a dozen times an hour pulls each source
572
- once, not a dozen times.
510
+ Downloaded sources are reused for seven days by default. Set `refreshTtlMs` to a
511
+ shorter interval or `0` to download on every boot:
573
512
 
574
513
  ```ts
575
514
  mastra({
@@ -585,11 +524,8 @@ mastra({
585
524
  });
586
525
  ```
587
526
 
588
- The record is keyed by the source AND the options that change what it contains
589
- (`skills`, `experimental`, `ref`), so narrowing a skill list or moving a `ref`
590
- re-downloads immediately rather than serving the previous selection for seven days.
591
- A missing or unreadable record is treated as a cache miss, never as a startup
592
- failure.
527
+ Changing a source's `skills`, `experimental`, or `ref` option refreshes it
528
+ immediately.
593
529
 
594
530
  ## Databricks AI Tools
595
531
 
@@ -776,8 +712,10 @@ same in either mode; chrome is not.
776
712
  ## Model Selection
777
713
 
778
714
  `model.buildModel()` adapts the generic resolver from
779
- [`@dbx-tools/model`](../model) to Mastra. It resolves the model per request,
780
- so OBO identity and request-specific overrides stay isolated.
715
+ [`@dbx-tools/model`](../model) to Mastra, then constructs a request-scoped
716
+ Vercel AI SDK ProviderV4 model through
717
+ [`@dbx-tools/model-protocol`](../model-protocol). It resolves the model per
718
+ request, so OBO identity and request-specific overrides stay isolated.
781
719
 
782
720
  Model priority is:
783
721
 
@@ -806,14 +744,16 @@ Use `serving.extractModelOverride()` and `serving.resolveServingConfig()` when
806
744
  building custom routes that should behave like the plugin's `/models` and stream
807
745
  routes.
808
746
 
809
- The serving fetch interceptor repairs provider-specific wire requirements for
810
- both `fetch(url, { body })` and `fetch(new Request(...))`. In particular,
747
+ The Chat provider uses a provider-local fetch from
748
+ `@dbx-tools/model-protocol`; Mastra does not patch `globalThis.fetch`. The
749
+ shared fetch repairs provider-specific wire requirements for both
750
+ `fetch(url, { body })` and `fetch(new Request(...))`. In particular,
811
751
  Databricks-hosted GPT 5.6 Chat Completions with function tools receives
812
752
  `reasoning_effort: "none"` even when a caller default selected another effort.
813
753
  Other Chat models receive no synthesized effort, while an explicit supported
814
754
  caller value is preserved. Responses-only models such as GPT Astra use the
815
755
  native Responses provider. Claude reasoning replay and Gemini/Claude structured
816
- response content continue through the same sanitizer.
756
+ response content continue through the same shared sanitizer.
817
757
 
818
758
  Responses turns set `store: false`. The OpenAI provider automatically includes
819
759
  encrypted reasoning state so a tool continuation sends the complete stateless
@@ -1082,8 +1022,7 @@ needs no extra wiring.
1082
1022
 
1083
1023
  ## Configuration Reference
1084
1024
 
1085
- The plugin config is intentionally centered on the AppKit lifecycle instead of
1086
- requiring callers to assemble a Mastra server by hand.
1025
+ The main plugin options are:
1087
1026
 
1088
1027
  - `agents` registers a single agent, an array, or a record keyed by stable agent
1089
1028
  ids. Records are best for UIs because the ids become route-visible.
@@ -1098,9 +1037,8 @@ requiring callers to assemble a Mastra server by hand.
1098
1037
  Pass `false` to disable it or an object with `topK`, `minScore`, and `ttlMs`
1099
1038
  overrides.
1100
1039
  - `workspaceTools` forwards Mastra's native workspace-tool configuration.
1101
- Reads do not require approval. Filesystem mutations require approval outside
1102
- the authenticated user's `/Workspace/Users/<email>` home. Explicit global or
1103
- per-tool settings override those defaults.
1040
+ All tools are enabled without approval by default. Global and per-tool
1041
+ settings can require approval or disable selected tools.
1104
1042
  - `remoteSkills` provisions `SKILL.md` sources from outside the workspace at
1105
1043
  startup (see [Remote Skills](#remote-skills)). Accepts a single source, a
1106
1044
  list, or an options bag with `failOnError`, `userEmail`,
@@ -1109,9 +1047,8 @@ requiring callers to assemble a Mastra server by hand.
1109
1047
  [Databricks AI Tools](#databricks-ai-tools)) or any URL-like.
1110
1048
  - `genieSpaces` maps aliases to Genie Space IDs (or to
1111
1049
  `{ spaceId, hint }` objects). Those aliases flow into tool names,
1112
- suggestions, and chart/data workflows. An alias present with no space id is a
1113
- wiring contradiction and fails at construction rather than silently
1114
- registering no Genie tools.
1050
+ suggestions, and chart/data workflows. Every configured alias needs a space
1051
+ id.
1115
1052
  - `genieAgentMode` defaults to `true` for the streaming Agent Mode API. Set it
1116
1053
  to `false` to force Conversation API polling. Pre-stream feature-disabled or
1117
1054
  preview-toggle responses fall back automatically.
@@ -1122,33 +1059,18 @@ requiring callers to assemble a Mastra server by hand.
1122
1059
  Explicit `true` fails startup unless an experiment id or name is configured.
1123
1060
  - `mcp` controls whether agents are exposed as MCP tools and how that server is
1124
1061
  named.
1125
- - `genieIdentity` picks the Databricks identity the agents' workspace calls run
1126
- as - the serving catalogue behind the model picker, Genie suggestions,
1127
- `ask_genie`, and the statement fetch behind a `[data:<id>]` embed. `"user"`
1128
- (default) is always on-behalf-of the signed-in user, so callers must be
1129
- members of the WORKSPACE, not just the Databricks account. `"service-principal"`
1130
- runs those calls as the app service principal instead, so any caller who can
1131
- open the app works even without workspace membership - useful when an app is
1132
- shared with an account-level group too large to add to the workspace. It
1133
- changes only the Databricks credential: memory threads, the per-user cache
1134
- namespace, and trace metadata still key off the forwarded user, at the cost
1135
- of per-user attribution in Genie / Unity Catalog. `"auto"` decides PER REQUEST:
1136
- OBO when the request actually carries an OBO token, service principal when it
1137
- does not. That is the mode for an app served through more than one door - a
1138
- container fronted by [`@dbx-tools/tunnel`](../../node/tunnel) serves both
1139
- email-code callers (no Databricks credential exists to forward) and the
1140
- platform front door on one port, and `"user"` would make every tunnel turn fail
1141
- with AppKit's `AuthenticationError` while `"service-principal"` would throw away
1142
- per-user scoping for the front-door callers who still have it. Falls back to
1143
- `MASTRA_GENIE_IDENTITY`. The decision itself lives in
1144
- [`@dbx-tools/appkit`](../appkit)'s `identity` module, so a non-Mastra plugin can
1145
- make the same call.
1062
+ - `genieIdentity` selects credentials for model discovery, Genie calls, and
1063
+ statement fetches. `"user"` uses OBO and requires workspace membership.
1064
+ `"service-principal"` lets account-level users call the app without workspace
1065
+ membership. `"auto"` uses OBO when the request includes it and otherwise uses
1066
+ the service principal. Memory threads, cache namespaces, and trace metadata
1067
+ remain user-scoped in all three modes. The environment fallback is
1068
+ `MASTRA_GENIE_IDENTITY`.
1146
1069
  - `apiAccess` chooses the route allowlist. Keep the default scoped mode for
1147
1070
  deployed apps.
1148
1071
 
1149
- Use this package when you want an AppKit-native agent runtime. Use the shared
1150
- schemas in [`@dbx-tools/shared-mastra`](../../shared/mastra) when building a
1151
- client that talks to these routes.
1072
+ Clients that call these routes can import the browser-safe schemas from
1073
+ [`@dbx-tools/shared-mastra`](../../shared/mastra).
1152
1074
 
1153
1075
  ## Modules
1154
1076
 
package/index.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  // Hand edits are overwritten on the next watch; this file is read-only.
4
4
 
5
5
  export const PACKAGE_IDENTIFIER = "@dbx-tools/appkit-mastra";
6
- export const PACKAGE_VERSION = "0.9.99";
6
+ export const PACKAGE_VERSION = "0.9.106";
7
7
  export * as agents from "./src/agents.ts";
8
8
  export * as chart from "./src/chart.ts";
9
9
  export * as chat from "./src/chat.ts";
@@ -27,7 +27,6 @@ export * as rest from "./src/rest.ts";
27
27
  export * as sandbox from "./src/sandbox.ts";
28
28
  export * as server from "./src/server.ts";
29
29
  export * as serving from "./src/serving.ts";
30
- export * as servingSanitize from "./src/serving-sanitize.ts";
31
30
  export * as skillPaths from "./src/skill-paths.ts";
32
31
  export * as statement from "./src/statement.ts";
33
32
  export * as storageSchema from "./src/storage-schema.ts";
@@ -38,7 +37,7 @@ export * as traceAttributes from "./src/trace-attributes.ts";
38
37
  export * as validation from "./src/validation.ts";
39
38
  export * as workspaces from "./src/workspaces.ts";
40
39
  export * as writer from "./src/writer.ts";
41
- export { FALLBACK_AGENT_ID, DEFAULT_AGENT_MAX_STEPS, DEFAULT_STYLE_INSTRUCTIONS } from "./src/agents.ts";
40
+ export { FALLBACK_AGENT_ID, DEFAULT_AGENT_MAX_STEPS, DEFAULT_TOOL_WORKFLOW_INSTRUCTIONS, DEFAULT_STYLE_INSTRUCTIONS } from "./src/agents.ts";
42
41
  export type { MastraTools, AppKitToolOptions, ToolkitOptions, MastraPluginToolkitProvider, MastraPlugins, MastraToolsFn, MastraAgentWorkspaceResolver, MastraAgentDefinition, AnyMastraAgentDefinition, MastraStorageConfigOverride, MastraMemoryConfigOverride, AgentDefaultModel, BuiltAgents } from "./src/agents.ts";
43
42
  export { chartPlanSchema, chartPlannerRequestSchema, chartToolOutputSchema } from "./src/chart.ts";
44
43
  export type { ChartPlannerRequest, ChartToolOutput, PrepareChartOptions, FetchChartOptions } from "./src/chart.ts";
package/lib/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export declare const PACKAGE_IDENTIFIER = "@dbx-tools/appkit-mastra";
2
- export declare const PACKAGE_VERSION = "0.9.99";
2
+ export declare const PACKAGE_VERSION = "0.9.106";
3
3
  export * as agents from "./src/agents.ts";
4
4
  export * as chart from "./src/chart.ts";
5
5
  export * as chat from "./src/chat.ts";
@@ -23,7 +23,6 @@ export * as rest from "./src/rest.ts";
23
23
  export * as sandbox from "./src/sandbox.ts";
24
24
  export * as server from "./src/server.ts";
25
25
  export * as serving from "./src/serving.ts";
26
- export * as servingSanitize from "./src/serving-sanitize.ts";
27
26
  export * as skillPaths from "./src/skill-paths.ts";
28
27
  export * as statement from "./src/statement.ts";
29
28
  export * as storageSchema from "./src/storage-schema.ts";
@@ -34,7 +33,7 @@ export * as traceAttributes from "./src/trace-attributes.ts";
34
33
  export * as validation from "./src/validation.ts";
35
34
  export * as workspaces from "./src/workspaces.ts";
36
35
  export * as writer from "./src/writer.ts";
37
- export { FALLBACK_AGENT_ID, DEFAULT_AGENT_MAX_STEPS, DEFAULT_STYLE_INSTRUCTIONS } from "./src/agents.ts";
36
+ export { FALLBACK_AGENT_ID, DEFAULT_AGENT_MAX_STEPS, DEFAULT_TOOL_WORKFLOW_INSTRUCTIONS, DEFAULT_STYLE_INSTRUCTIONS } from "./src/agents.ts";
38
37
  export type { MastraTools, AppKitToolOptions, ToolkitOptions, MastraPluginToolkitProvider, MastraPlugins, MastraToolsFn, MastraAgentWorkspaceResolver, MastraAgentDefinition, AnyMastraAgentDefinition, MastraStorageConfigOverride, MastraMemoryConfigOverride, AgentDefaultModel, BuiltAgents } from "./src/agents.ts";
39
38
  export { chartPlanSchema, chartPlannerRequestSchema, chartToolOutputSchema } from "./src/chart.ts";
40
39
  export type { ChartPlannerRequest, ChartToolOutput, PrepareChartOptions, FetchChartOptions } from "./src/chart.ts";