@dbx-tools/appkit-mastra 0.9.99 → 0.9.105
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 +139 -217
- package/index.ts +2 -3
- package/lib/index.d.ts +2 -3
- package/lib/index.js +3 -4
- package/lib/src/agents.d.ts +2 -0
- package/lib/src/agents.js +62 -14
- package/lib/src/chat.d.ts +3 -1
- package/lib/src/chat.js +98 -12
- package/lib/src/config.d.ts +7 -1
- package/lib/src/config.js +6 -2
- package/lib/src/model.d.ts +3 -6
- package/lib/src/model.js +11 -94
- package/lib/src/monty-sandbox.d.ts +1 -2
- package/lib/src/monty-sandbox.js +3 -3
- package/lib/src/plugin.js +3 -1
- package/lib/src/workspaces.js +17 -49
- package/lib/tsconfig.tsbuildinfo +1 -1
- package/package.json +16 -22
- package/src/agents.ts +61 -12
- package/src/chat.ts +103 -11
- package/src/config.ts +13 -2
- package/src/model.ts +10 -108
- package/src/monty-sandbox.ts +7 -6
- package/src/plugin.ts +2 -0
- package/src/workspaces.ts +32 -74
- package/lib/src/serving-sanitize.d.ts +0 -6
- package/lib/src/serving-sanitize.js +0 -7
- package/src/serving-sanitize.ts +0 -19
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
|
-
|
|
7
|
-
Databricks
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
|
345
|
-
|
|
346
|
-
|
|
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
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
and later turns
|
|
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
|
|
366
|
-
|
|
367
|
-
|
|
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
|
-
|
|
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
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
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
|
-
|
|
417
|
-
|
|
418
|
-
|
|
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
|
-
|
|
430
|
-
|
|
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
|
-
|
|
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
|
|
504
|
-
|
|
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
|
-
|
|
510
|
-
workspace.
|
|
511
|
-
|
|
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
|
|
526
|
-
the
|
|
527
|
-
|
|
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
|
-
|
|
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
|
-
|
|
567
|
-
|
|
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
|
-
|
|
589
|
-
|
|
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
|
|
780
|
-
|
|
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
|
|
810
|
-
|
|
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
|
|
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
|
-
|
|
1102
|
-
|
|
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.
|
|
1113
|
-
|
|
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`
|
|
1126
|
-
|
|
1127
|
-
`
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
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
|
-
|
|
1150
|
-
|
|
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.
|
|
6
|
+
export const PACKAGE_VERSION = "0.9.105";
|
|
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.
|
|
2
|
+
export declare const PACKAGE_VERSION = "0.9.105";
|
|
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";
|