0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
Commit graph

29 commits

Author SHA1 Message Date
mastra-platform[bot]
eb57671973
fix(connect): default OpenAI create-image tool to gpt-image-2.5-sunburst (#30364)
> Opened by @arthurfiorette

The OpenAI create-image tool in `@mastra/connect` defaulted to
`gpt-image-1`, which OpenAI retired on October 23, 2026. Calls that
omitted `model` failed. This changes the default (and the schema
description) to `gpt-image-2.5-sunburst`, OpenAI's recommended
replacement, so those calls work again. A changeset is included.

Test plan: not run locally. The change replaces one string default and
the matching description text.

Fixes #30329

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

**ELI5:** The tool that makes images used an old AI model when the
caller did not name one. OpenAI turned that model off, so those calls
failed. This change makes the tool use a newer model by default, and it
keeps that default when the provider code is regenerated.

## Overview

This change updates the default model of the OpenAI create-image tool in
`@mastra/connect`. The default changes from `gpt-image-1` to
`gpt-image-2.5-sunburst`. OpenAI retired `gpt-image-1` on October 23,
2026. Calls that omit `model` failed after that date. This change
addresses those calls.

The generator script also changes. Without this change, regenerating the
OpenAI provider would restore the old default. The generator now applies
the same default. It uses `replaceOnce` and throws if an expected
template pattern does not occur exactly once.

## Changes

- `packages/connect/src/providers/openai/tools/create-image.ts`: Changes
the fallback model used when `input.model` is omitted. Changes the
matching schema description to name the new default. Explicitly passed
models are unchanged.
- `packages/connect/scripts/generate-provider.ts`: Adds an OpenAI
`create-image` override. The override changes the generated
model-default description and the execution fallback to
`gpt-image-2.5-sunburst`. `applyProviderActionOverrides` applies this
override for the OpenAI create-image action.
- `packages/connect/src/__tests__/provider-commands.test.ts`: The OpenAI
image action fixture accepts an optional `model` and sends it with the
prompt. The fixture defaults to `gpt-image-1` when `model` is omitted. A
new test asserts that generated OpenAI tools default to
`gpt-image-2.5-sunburst`, document that default, and do not reference
`gpt-image-1`.
- `packages/connect/src/providers/openai/.manifest.json`: Updates the
SHA-256 value for `tools/create-image.ts`.
- `.changeset/connect-image-default-sunburst.md`: Adds a patch changeset
for `@mastra/connect`. The changeset documents the default model change.

## Scope

- 5 files changed.
- 55 lines added and 5 lines removed.
- No exported or public declarations changed.

## Verification

- The author states that tests were not run locally.
- No completed CI or test results were available for review.

## Linked issue

- Issue `#30329` reports the retired default model. It names
`gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` as replacement
options. This change uses `gpt-image-2.5-sunburst`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-11-13 16:49:44 -08:00
Leo
10b2ac6614
fix(connect): accept Fireflies keyword lists and numeric speaker ids (#29538)
## Summary

`fireflies_get_transcript` in `@mastra/connect` threw a ZodError on most
real Fireflies transcripts. Two fields cause it: the live API sends
`summary.keywords` as a list of strings and `speakers[].id` as a number,
but the schema accepts only strings. `fireflies_list_transcripts` kept
working, so agents could list calls but couldn't read any of them.

The tool now accepts both shapes from Fireflies. Its output doesn't
change: keywords come back as one comma-separated string and speaker ids
as strings. That's the same way the tool already handles `action_items`
and sentence `speaker_id`.

`src/providers/**` is generated from NangoHQ/integration-templates and
can't be hand-edited, and upstream has no fix yet. So the change is a
Mastra-side generator override, next to the existing Office
`get-user-drive` override, and Fireflies is regenerated from its
existing pin (`9f836014ab8b`):

```diff
 // scripts/generate-provider.ts, fireflies/get-transcript only
 ProviderSummarySchema
+  keywords: string | string[]          -> joined with ', ' in the output
 SpeakerSchema
+ProviderSpeakerSchema: id string | number  -> String(id) in the output
 TranscriptSchema
-  speakers: z.array(SpeakerSchema)
+  speakers: z.array(ProviderSpeakerSchema)
```

Each rewrite has to match the template exactly once. If upstream changes
any of those pieces, generation stops with "the upstream template shape
changed" instead of quietly shipping the old schema. Regenerating
changes only `tools/get-transcript.ts` and its manifest checksum; the
other 26 Fireflies files are unchanged.

I checked the rest of the response schema against Fireflies' published
GraphQL types (Transcript, Summary, Speaker, Sentence,
MeetingAttendeeModel, MeetingInfo, MeetingAnalytics). Only these two
fields break. The sentence fields were already fixed in #27156, and
everything else matches.

## Evidence

The tests call the public `tools()` resolver against a real localhost
HTTP server standing in for the Mastra platform. Only the Fireflies
GraphQL payload is scripted, using the shape from the issue.

- **Before** (main's generated tool, new tests): 3 failed, 5 passed. The
failures are the issue's errors:
  ```
× returns a transcript whose keywords are a list and whose speaker ids
are numbers
  × returns a transcript whose keywords are a list
  × returns a transcript whose speaker ids are numbers
data.transcript.summary.keywords: Invalid input: expected string,
received array
data.transcript.speakers.0.id: Invalid input: expected string, received
number
  ```
**After:** `src/__tests__/fireflies-transcript.test.ts` passes 8 of 8.
Covered: list keywords, numeric ids, both together, string inputs, an
empty list (returns `''`), nulls kept as null, omitted fields left
absent, and a non-string, non-number id still rejected.
- **Generator:** `provider-commands.test.ts` adds 8 tests: one checks
that the override is applied, and 7 drift cases (one per rewrite) check
that a changed template fails generation. With the override switched
off, they fail.
- `@mastra/connect` suite: 482 of 482 pass. `tsc --noEmit`, `oxlint
--type-aware` and `oxfmt --check` pass on the changed files.
- **Not checked:** a live Fireflies account. The smoke scenario only
probes a synthetic transcript id, so it can't parse a real transcript
body.

## Merge Danger

**Door:** two-way. Revert the commit, or drop the override and
regenerate.

**Blast radius:** `fireflies_get_transcript` only. The output type is
the same, so existing callers keep working.

Follow-ups:
- Fix this in NangoHQ/integration-templates, then move the Fireflies pin
and delete the override.
- Consider returning `keywords` as `string[]` in a future minor release,
to match `fireflies_list_transcripts`. Joining with `', '` loses the
boundary of a keyword that itself contains a comma.

Closes #29401

## Council review

| Round | Sol (GPT-6.1 Sol): Correctness / Tests / Scope / Code quality
| Opus 5.5: Correctness / Tests / Scope / Code quality | Grok 4.7 |
|---|---|---|---|
| 1 | 9.5 / 9 / 10 / 9 | not seated (Sol-only round) | empty seat |
| 2 | 9 / 9 / 10 / 9 | 9 / 9 / 9 / 8.5 | empty seat |
| 3 | 10 / 9.5 / 10 / 10 | 9 / 9 / 9 / 9 | empty seat |

Created with Claude Opus 5.5 in T3 Code.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5
Fireflies sometimes sends transcript details in formats this tool did
not expect. This change lets the tool read those details and return them
in its existing format.

## Summary
- Accept `summary.keywords` as strings or string arrays. Join arrays
with `", "`.
- Accept speaker IDs as strings or numbers. Convert numeric IDs to
strings.
- Add a Fireflies `get-transcript` generator override.
- Stop generation when an expected template pattern does not match
exactly once.
- Add regression tests for normalization, null and omitted values,
invalid speaker IDs, and template drift.
- Add a patch changeset for `@mastra/connect`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 11:22:19 -05:00
arctic-char
b244478626
fix(connect): unblock Excel workbook deletes and fix Microsoft Office smoke scenarios (#30065)
## Description

The Excel delete workbook tool failed with a 423 "resource locked" error
after the workbook was edited. Graph's sessionless workbook writes (like
`update_range`) leave a co-authoring lock that lasts about 30 minutes,
so deletes failed until it expired. The delegated Excel delete-workbook
tool now sends `Prefer: bypass-shared-lock`:

```ts
await platformProxy.delete({
  endpoint: `/v1.0/me/drive/items/${encodeURIComponent(input.itemId)}`,
  headers: { Prefer: 'bypass-shared-lock' },
  // ...
});
```

The header is injected by the provider generator so it survives
regeneration, and a generator test covers it. The client-credentials
Excel variant is unchanged. One tradeoff: the bypass also overrides a
lock held by a person who has the workbook open, so the file goes to the
recycle bin anyway. `NangoHQ/integration-templates` is no longer
available, so the generated tool and manifest checksum were updated to
match the generator's output instead of regenerated.

While running the Microsoft smoke tests live, I also fixed the
scenarios. Word now sends `content` instead of `contentBase64`. On
personal accounts, Excel treats the tenant-only calls (users, sites) as
skips, and it retries read-after-write checks to absorb lag from
sessionless writes. PowerPoint now generates a valid minimal .pptx, so
PDF export no longer rejects it as corrupt, and finds copies by listing
the drive root instead of waiting for the search index.

## Related issue(s)

None, found while running the live Microsoft smoke tests.

## Type of change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [ ] I have linked the related issue(s) in the description above
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

## Test plan

- `pnpm --filter @mastra/connect smoke-test` with Word, Excel,
PowerPoint, Teams and Outlook: 5/5 pass live, no leaked files. The Excel
delete succeeds right after `update_range`; without the header it
returns 423.
- The generator test fails without the override and passes with it.
- In a clean Linux container: frozen-lockfile install, `turbo build
--filter @mastra/connect`, and `tsc` all pass. The connect tests pass
apart from intermittent 5s timeouts in `provider-commands.test.ts`,
which also happen on `main`.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## ELI5

This PR helps Excel delete files that remain temporarily locked after
editing. It also makes Microsoft Office smoke tests use valid files and
handle delayed results.

## Changes

- Add `Prefer: bypass-shared-lock` to delegated Excel `delete-workbook`
requests.
- Keep the client-credentials Excel variant unchanged.
- Add generator tests for both variants.
- Update the generated tool and manifest checksum.
- Add minimal XLSX and PPTX builders.
- Retry Excel read-after-write checks.
- Skip unsupported tenant-only operations for personal accounts.
- Find copied PowerPoint files by listing the drive root.
- Send Word updates with `content` instead of `contentBase64`.
- Add a patch changeset for `@mastra/connect`.

## Validation

The PR reports passing live smoke tests for Word, Excel, PowerPoint,
Teams, and Outlook. It also reports passing installation, build, and
TypeScript checks. Connect tests passed except for intermittent
`provider-commands.test.ts` timeouts also reported on `main`.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-11-11 11:09:00 -05:00
Lennart
1025e7eeff
docs(connect): one Connect page and one integration page per provider (#29465)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
2026-11-05 10:28:52 -08:00
arctic-char
5af331d0c2
feat(connect): add SharePoint Online toolset (#26284)
## Summary

Adds the SharePoint Online toolset to `@mastra/connect` (53 tools).

Generated from the shared NangoHQ/integration-templates pin
(bb789a55bfcf) via the add-provider workflow. Largest Microsoft 365
toolset in this split.

Split out of #25597 so each toolset ships as its own reviewable PR.

## Scope

- `packages/connect/src/providers/sharepoint-online/` — `53`
auto-generated tool files, `tools.ts`, `index.ts`, `.manifest.json`
- `packages/connect/src/providers/index.ts` — new import + barrel entry
- `packages/connect/src/__tests__/registry.test.ts` — new ID in the
expected provider list
- Changeset: `@mastra/connect` minor

## Test plan

- [ ] `pnpm --filter @mastra/connect test` passes
- [ ] `pnpm --filter @mastra/connect lint` clean
- [ ] `pnpm --filter @mastra/connect generate:provider-docs` regenerates
`reference/connect/providers.mdx` (run before merging to pick up the new
row and tool count)
- [ ] Smoke scenario authored + `pnpm smoke-test --provider
sharepoint-online` passes against a real connection (tracked in
PLTFRM-2551)

## Follow-ups

Tracked in Linear PLTFRM-2551: platform catalog entry, OAuth app,
scopes, smoke scenario, docs, and launch checklist.

## Account-aware smoke coverage

- exercises all 53 SharePoint Online tools for work/school connections
- reads `MASTRA_SMOKE_MICROSOFT_ACCOUNT_TYPE` before making Graph calls
- self-skips with an explicit work/school requirement when a personal
account is selected
- keeps the existing run-scoped SharePoint cleanup lifecycle


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

This PR adds tools that let Mastra work with SharePoint Online. They
help an agent find and manage sites, files, lists, and pages, including
downloading file content.

## Summary

- Adds 53 SharePoint Online tools to `@mastra/connect` for sites, drives
and drive items, lists and list items, content types, columns, and site
pages.
- Registers the provider and adds it to the provider reference.
- Adds an opt-in smoke-test scenario. It skips personal Microsoft
accounts and requires a configured test site. When a test-tenant grantee
is configured, it tests permission operations without sending
invitations. Otherwise, it probes those operations with synthetic IDs.
The scenario uses run-scoped records and attempts cleanup.

## Validation

The supplied information does not confirm test, lint, or
documentation-generation results. The real-connection smoke test was
listed as planned validation, but its completion is not confirmed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: Saba Tchikhinashvili <saba.chikhina@gmail.com>
2026-10-30 17:53:59 -04:00
arctic-char
c293432bd4
feat(connect): add Microsoft Excel toolset with proxy pagination and safer Graph cursors (#26283)
## Summary

Adds the Microsoft Excel toolset to `@mastra/connect` with 27 Microsoft
Graph tools, proxy pagination, endpoint-scoped cursor validation, and an
account-aware smoke scenario.

The provider now matches Platform's delegated OAuth model.
`get_user_drive` resolves the connected user's OneDrive through
`/me/drive` when `userId` is omitted, while retaining the explicit
tenant-user path for work/school accounts. The smoke scenario tries the
connected-user drive first and treats tenant-directory and SharePoint
failures as account capability boundaries rather than connection
failures.

## What changed

- generated 27 Excel tools from the shared Nango template pin under the
delegated `microsoft-excel` provider ID
- added `/me/drive` discovery for the connected user
- preserved the Graph cursor constraints for `list_users`, `list_sites`,
and `list_workbooks`
- added runtime pagination for `list_worksheets`
- made Graph next-page query handling preserve `$skiptoken` values
- surfaced nested provider error codes when Graph returns an empty
message
- covered all 27 tools in the Excel smoke scenario

The shared generator/runtime support is split into #27314.

## Test plan

- [x] `pnpm --filter @mastra/connect test` — 18 files, 379 tests, `tsc
--noEmit` clean
- [x] `pnpm --filter @mastra/connect lint`
- [x] `pnpm turbo build:lib --filter=@mastra/connect`
- [x] provider regeneration — 27 tools, 0 skipped
- [x] smoke scenario static validation — 27/27 tools covered, 0
input-shape findings
- [ ] live delegated OAuth smoke run — Platform credentials are
unavailable in the current review environment; required before merge

## Follow-up

Platform launch work remains tracked in PLTFRM-2553.

## Account-aware smoke coverage

- exercises all 27 Excel tools
- uses `MASTRA_SMOKE_MICROSOFT_ACCOUNT_TYPE` to classify Microsoft Graph
workbook API limitations
- skips the 19 known personal-account-unsupported workbook operations
only when the selected account is explicitly personal and Graph returns
a capability error
- preserves failures for unexpected responses and work/school accounts


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

This adds Microsoft Excel tools to Mastra Connect so agents can work
with Excel files in Microsoft 365. It also improves how Connect follows
Graph pages and reports Graph errors.

## What changed

- Added the delegated `microsoft-excel` provider with 27 tools for
drives, workbooks, worksheets, ranges, tables, charts, defined names,
users, and sites.
- When `userId` is omitted, `getUserDrive` now uses the connected user’s
`/me/drive`. An explicit `userId` still selects that user’s drive.
- Added pagination for `list_worksheets` and URL validation for Graph
cursors used by user, site, and workbook listing tools.
- Updated proxy query merging to preserve existing URL parameters. Error
details now include nested provider codes when the error message is
empty.
- Added provider generation support, documentation, a smoke-test
scenario, and changesets.

## Validation

The PR objectives report passing Connect tests, lint, library build,
provider regeneration, and smoke-scenario static validation. A live
delegated OAuth smoke run was not tested because Platform credentials
were unavailable.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: Roamin <97863888+roaminro@users.noreply.github.com>
2026-10-30 17:19:28 -04:00
arctic-char
246621d1c4
feat(connect): add Microsoft Word toolset (#26282)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-28 18:09:27 -07:00
arctic-char
9afe13546d
feat(connect): add Outlook (Microsoft 365 mail) toolset (#26281)
## Summary

Adds the Outlook (Microsoft 365 mail) toolset to `@mastra/connect` (30
tools).

Generated from the shared NangoHQ/integration-templates pin
(bb789a55bfcf) via the add-provider workflow. Uses Microsoft Graph
through the platform proxy.

Split out of #25597 so each toolset ships as its own reviewable PR.

## Scope

- `packages/connect/src/providers/outlook/` — `30` auto-generated tool
files, `tools.ts`, `index.ts`, `.manifest.json`
- `packages/connect/src/providers/index.ts` — new import + barrel entry
- `packages/connect/src/__tests__/registry.test.ts` — new ID in the
expected provider list
- Changeset: `@mastra/connect` minor

## Test plan

- [ ] `pnpm --filter @mastra/connect test` passes
- [ ] `pnpm --filter @mastra/connect lint` clean
- [ ] `pnpm --filter @mastra/connect generate:provider-docs` regenerates
`reference/connect/providers.mdx` (run before merging to pick up the new
row and tool count)
- [ ] Smoke scenario authored + `pnpm smoke-test --provider outlook`
passes against a real connection (tracked in PLTFRM-2549)

## Follow-ups

Tracked in Linear PLTFRM-2549: platform catalog entry, OAuth app,
scopes, smoke scenario, docs, and launch checklist.

## Account-aware smoke coverage

- exercises all 30 Outlook tools
- uses `MASTRA_SMOKE_MICROSOFT_ACCOUNT_TYPE` to distinguish personal and
work/school capability failures
- route-probes operations unavailable to personal accounts instead of
treating them as credential failures
- never sends external email during smoke runs


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

This change adds Outlook support to `@mastra/connect`. It gives
applications tools to work with Microsoft 365 email, folders,
attachments, calendars, and events through Microsoft Graph.

## Changes

- Added and registered the Outlook provider with 30 tools.
- Added tools for mail, drafts, replies, attachments, folders,
calendars, and events.
- Added input and output validation, pagination, retries, response
mapping, and error handling.
- Added provider documentation, registry coverage, metadata, and a minor
changeset with a usage example.
- Added an Outlook smoke-test scenario with account capability checks,
probes for unsupported operations, and cleanup.

## Validation

Test and lint results were not provided. The listed validation plan
includes Connect tests, linting, provider documentation generation, and
a real-connection smoke test.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: labifrancis <10200603+labifrancis@users.noreply.github.com>
2026-10-28 16:29:58 -04:00
arctic-char
3332a987e5
feat(connect): add Microsoft PowerPoint toolset (#26285)
## Summary

Adds the Microsoft PowerPoint toolset to `@mastra/connect` with 18
Microsoft Graph tools and a full lifecycle smoke scenario for Platform's
delegated OAuth model.

The shared upstream template is still named
`microsoft-powerpoint-oauth2-cc`, so it is generated locally as
`microsoft-powerpoint`. The delegated Office adapter changes
`get_user_drive` to resolve the connected user's OneDrive through
`/me/drive` when `userId` is omitted, while retaining the explicit
tenant-user path for work/school accounts.

## Scope

- `packages/connect/src/providers/microsoft-powerpoint/` — 18 generated
tools, registry entry, and manifest
- delegated current-user drive discovery via `/me/drive`
- account-aware drive discovery in the smoke scenario
- presentation create/read/update/share/copy/move/delete lifecycle
coverage
- generated provider reference documentation

The shared generator/runtime support is split into #27314.

## Test plan

- [x] `pnpm --filter @mastra/connect test` — 17 files, 343 tests, `tsc
--noEmit` clean
- [x] `pnpm --filter @mastra/connect lint`
- [x] `pnpm turbo build:lib --filter=@mastra/connect`
- [x] provider regeneration — 18 tools, 0 skipped
- [ ] live delegated OAuth smoke run

## Follow-up

Platform launch work remains tracked in PLTFRM-2554.

## Account-aware smoke coverage

- exercises all 18 PowerPoint tools
- reports the selected Microsoft account type in the scenario output
- classifies tenant-directory and SharePoint discovery errors as
capability skips only for explicit personal-account runs
- uses anonymous sharing for personal accounts and organization sharing
for work/school accounts


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

This PR adds tools that let Mastra work with Microsoft PowerPoint files
stored in OneDrive or SharePoint. The tools can find, create, read,
update, share, copy, move, and delete presentations.

## Summary

- Adds 18 Microsoft Graph tools for presentation and drive operations,
sharing, permissions, versions, thumbnails, and content export.
- Registers the `microsoft-powerpoint` provider and adds its manifest
and documentation.
- Uses `/me/drive` to find the current user’s drive when no `userId` is
provided.
- Adds a smoke-test scenario for the presentation lifecycle, with
account-aware handling for personal and work or school accounts.

## Validation

The PR objectives report that the connect test suite passed with 17
files and 343 tests, and that `tsc --noEmit`, lint, library build, and
provider regeneration completed. A live delegated OAuth smoke run is
unchecked.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: Grayson Hicks <graysonhicks@gmail.com>
2026-10-26 12:04:14 -04:00
arctic-char
c3bf4fd583
feat(connect): add OneDrive toolset (#26287)
## Summary

Adds the OneDrive toolset to `@mastra/connect` (20 tools).

Generated from the shared NangoHQ/integration-templates pin
(bb789a55bfcf) via the add-provider workflow. Uses Microsoft Graph
through the platform proxy, including `responseType: 'arraybuffer'` for
binary payloads.

Split out of #25597 so each toolset ships as its own reviewable PR.

## Scope

- `packages/connect/src/providers/one-drive/` — `20` auto-generated tool
files, `tools.ts`, `index.ts`, `.manifest.json`
- `packages/connect/src/providers/index.ts` — new import + barrel entry
- `packages/connect/src/__tests__/registry.test.ts` — new ID in the
expected provider list
- Changeset: `@mastra/connect` minor

## Test plan

- [ ] `pnpm --filter @mastra/connect test` passes
- [ ] `pnpm --filter @mastra/connect lint` clean
- [ ] `pnpm --filter @mastra/connect generate:provider-docs` regenerates
`reference/connect/providers.mdx` (run before merging to pick up the new
row and tool count)
- [ ] Smoke scenario authored + `pnpm smoke-test --provider one-drive`
passes against a real connection (tracked in PLTFRM-2550)

## Follow-ups

Tracked in Linear PLTFRM-2550: platform catalog entry, OAuth app,
scopes, smoke scenario, docs, and launch checklist.

## Account-aware smoke coverage

- exercises all 20 OneDrive for Business tools through a run-scoped file
lifecycle
- reads `MASTRA_SMOKE_MICROSOFT_ACCOUNT_TYPE` before making Graph calls
- self-skips with an explicit work/school requirement when a personal
account is selected
- avoids external invitations and cleans up created files and folders


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

This adds tools that let applications work with files and folders in
OneDrive through `@mastra/connect`. It also registers and documents the
provider and adds a smoke-test scenario for connected accounts.

## Changes

- Adds 20 OneDrive tools for drive discovery, file and folder
operations, sharing, permissions, search, versions, and uploads.
- Registers the `one-drive` provider and updates the provider
documentation and display name.
- Adds a smoke-test scenario that skips personal Microsoft accounts and
exercises file and folder operations with run-specific names and
cleanup.
- Adds a minor changeset for `@mastra/connect`.

## Testing

The package tests, lint, provider-doc generation, and real-connection
smoke test are listed as unchecked. No passing test results are
reported.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-26 09:21:11 -04:00
arctic-char
c2e7dcc219
fix(connect): generate Office tools for delegated OAuth (#27314)
## Summary
- adapt shared Microsoft Office templates to resolve the connected
user's OneDrive through `/me/drive` when no user ID is provided
- preserve generic `nango.proxy()`, typed proxy calls, and `randomUUID`
template patterns during generation
- keep the client-credentials variants unchanged while generating
delegated Excel, Word, and PowerPoint toolsets

## Test plan
- `pnpm test` in `packages/connect` (340 tests)
- `pnpm lint` in `packages/connect`
- `pnpm build:lib` in `packages/connect`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## ELI5

This change helps Mastra find provider templates that are linked under
another name. It also helps generated Microsoft Office tools use the
signed-in user’s OneDrive, while keeping existing ways to make provider
requests available.

## Changes

- Provider discovery now includes symlinked templates that resolve to a
provider with an `actions` entry.
- Office Excel, Word, and PowerPoint drive actions use `/v1.0/me/drive`
when no user ID is provided. When a user ID is present, generation keeps
the user-specific endpoint.
- Provider generation preserves supported `nango.proxy()` and typed
proxy patterns. It also rewrites supported unaliased `randomUUID`
imports to `globalThis.crypto.randomUUID()`.
- `PlatformProxy` now exposes `proxy()`. The method accepts an optional
HTTP method and defaults to `GET`.
- Added tests for proxy behavior, symlinked provider aliases, delegated
Office generation, and supported template patterns.

## Testing

The author reports running `pnpm test` (340 tests), `pnpm lint`, and
`pnpm build:lib` in `packages/connect`. These results were not
independently verified.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-10-23 13:18:47 -04:00
Max Katz
fe048f7950
chore(lint): require import type for type-only imports (#27642)
Lint now requires `import type` for imports used only as types, as
`oxlint.config.ts` always intended. The two rules have matched no files
since mastra-ai/mastra#20173 broke their override's glob, so the repo
drifted into mixing `import { type X }`, `import { X }` for types, and
`import type`. This turns them back on and fixes the existing imports.
No runtime behavior changes.

## What changed

- `import/consistent-type-specifier-style` and
`typescript/consistent-type-imports` go from `off` to `error`.
- 186 files: type-only imports become `import type { … }`, split from
value imports where a statement had both. Done with `oxlint --fix` plus
6 files the fixer left with inline `type` specifiers, then `oxfmt`.
- `disallowTypeAnnotations` is now `false`: `typeof import('x')` is
already type-only, and 97 of its 112 uses are the
`vi.importActual<typeof import('./x')>()` pattern in tests.

## Could this change behavior?

Only where a package keeps imports at runtime (`verbatimModuleSyntax`,
via `tsconfig.node.json`) and a statement became fully `import type`,
since that drops the module load. That happens in 18 places: 11 in
tests, and in source `GithubAppIdentity` (factory), `Workspace`,
`SpanType`, `Knowledge` and `WORKSPACE_TOOLS` (core), `Observable` from
`rxjs` (nestjs), and `zod` / `@mastra/mcp` in the server adapter test
suite. None of those modules run code at load time.

## Scope

The other rules the broken glob turned off (`no-unused-vars`,
`no-console`/`no-debugger`, `ban-ts-comment`, `no-require-imports`, the
test-file import ban) stay off for their own PRs.

## Testing

1. `pnpm lint`: passes (the 13 `only-export-components` warnings are
already on `main`).
2. `pnpm turbo build` for the 34 changed packages and `typecheck` for
the ones that have it: pass.
3. The test files that lost a runtime import: pass (core, server,
observability, factory, voice).
2026-10-19 17:35:21 +04:00
arctic-char
8181db5e43
fix(connect): google-drive shared-drive writes + fireflies transcript schema (template bumps) (#27156)
Agents could not write to shared Google Drives (PLTFRM-2670) because
create-folder, move-file, and upload-document never sent
`supportsAllDrives=true`, and `fireflies_get_transcript` failed
validation (PLTFRM-2669) because Fireflies returns numeric
`speaker_id`/`start_time`/`end_time` where the schema expected strings.

Both are fixed upstream in NangoHQ/integration-templates#723 and
NangoHQ/integration-templates#724. This bumps the google-drive and
fireflies template pins to those PR heads and regenerates the toolsets.
The google-drive regen also picks up two new upstream tools,
`google_drive_export_file` and `google_drive_list_revisions`, now
covered in the smoke scenario (export is probed since the toolset cannot
bootstrap a Workspace file). Once the upstream PRs merge, the pins
should collapse back to a single main SHA.

Security review done on the regenerated diff: outside the three param
additions and the two new tools (proxied endpoints, encoded path params,
no credential access), every file only changed its generated-from SHA
header.

Verified with `pnpm --filter @mastra/connect test` (335 passing), lint,
build, and the coverage audit (google-drive 32/32, fireflies 27/27). A
live smoke run against a platform project (`smoke-test --provider
google-drive --provider fireflies`) still needs its pass counts added
here — I don't have `MASTRA_PLATFORM_SECRET_KEY` locally.

Fixes PLTFRM-2670, PLTFRM-2669

Co-Authored-By: mastracode
<284800079+mastra-platform[bot]@users.noreply.github.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This update helps Google Drive work with shared drives and adds tools to
export files and list file revisions. It also helps Fireflies process
transcript details when the service sends numbers instead of text.

## Changes

- Added `supportsAllDrives=true` to Google Drive folder creation, file
moves, and document uploads.
- Added and registered `google_drive_export_file` and
`google_drive_list_revisions`.
- Updated the Google Drive smoke scenario to check revision listing and
file export.
- Updated the Fireflies transcript tool to accept numeric or string
speaker IDs and timestamps, then normalize values before returning them.
- Updated the Google Drive and Fireflies integration-template pins and
regenerated provider files.
- Updated the provider reference documentation to list the two new
Google Drive tools.

## Validation

The author reports 335 passing tests, successful lint and build runs,
and successful coverage audits for both provider toolsets. A live smoke
run against a platform project remains unverified because the author
does not have `MASTRA_PLATFORM_SECRET_KEY` locally.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-16 13:40:42 -04:00
Taofeeq Oluderu
6dc66e6c69
feat(connect): add Microsoft Teams to Mastra Connect (tools + channel) (#27094)
## Summary

Ships Microsoft Teams as a fully supported Mastra Connect provider: 25
Graph-backed tools and a messaging channel with delegated bot
provisioning via the Teams Dev Portal.

- Un-excludes `microsoft-teams` from the provider docs and documents the
channel setup (no customer-side Azure app registration needed — Mastra
provisions the Dev Portal bot; `MASTRA_ENCRYPTION_KEY` required).
- `channels()` now fails with a configuration error when
`MASTRA_ENCRYPTION_KEY` is missing **and** a Teams connection is active.
The check runs at resolution time, so Slack/Discord-only projects are
unaffected.
- `@mastra/teams` provisions **SingleTenant** bots by default, deriving
the tenant from the signed-in account's Graph token (`tid` claim).
Microsoft no longer accepts new multi-tenant bot registrations; explicit
`appType: 'MultiTenant'` remains available as an opt-out.
- Smoke fixes: HTTPS placeholder messaging endpoint (Dev Portal rejects
non-HTTPS), corrected scenario inputs for `create_chat` and
`create_channel_tab`.

Closes PLTFRM-2543.

## Test plan

- `@mastra/connect` vitest: 336/336 pass; tsc clean
- `@mastra/teams` vitest: 48/48 pass; tsc clean
- Live tools smoke (`--provider microsoft-teams`): **25/25 pass** — real
team/channel/message/reply lifecycle plus probe tools proving endpoint
routing; cleanup deletes the created channel
- Live channels smoke (`smoke-test:channels`): **3/3 suites pass, 0
fail** — resolver contract (12 checks), server mount + webhook 404s (6
checks), Teams layer 4 (12 checks): live Graph `/me`, Dev Portal
secondary token, full bot provision via `connect()` → active
installation → `disconnect()` → Entra app deleted (Graph 404)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

Mastra Connect can now connect to Microsoft Teams, so people can talk to
agents in Teams and agents can use Teams tools. Teams bot credentials
remain encrypted when no environment encryption key is configured.

## Summary

- Adds Microsoft Teams as a Connect channel and provider, with 25
Microsoft Graph-backed tools and generated provider documentation.
- Uses `MASTRA_ENCRYPTION_KEY` when configured. Otherwise, derives an
encryption key from the platform access token and logs a warning.
Rotating that token can make stored credentials unreadable; disconnect
and reconnect to provision them again.
- Defaults delegated bot provisioning to single-tenant. The provider
derives the tenant from the Graph token’s `tid` claim unless
`appTenantId` is set. Explicit multi-tenant provisioning remains
available.
- Documents Teams setup, tenant admin consent, bot provisioning, and the
Teams Developer Portal packaging step.
- Updates Teams smoke-test inputs and uses an HTTPS endpoint for bot
provisioning.

## Validation

The PR objectives report passing tests, TypeScript checks, and smoke
tests. These results are author-reported and were not independently
verified.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-16 15:17:59 +01:00
Taofeeq Oluderu
3df140f930
fix(connect): regenerate linear and fireflies from templates#708 (#26516)
## Summary

Repins the `linear` and `fireflies` providers to the head of
[NangoHQ/integration-templates#708](https://github.com/NangoHQ/integration-templates/pull/708)
(`36cd8a2a`) and regenerates both toolsets. Fixes three bug-bash
findings where valid vendor responses crashed tool calls:

- **Linear attachment tools rejected null creator emails** —
`linear_get_attachment` / `linear_list_attachments` now accept `email:
null`, which Linear's GraphQL API returns for external users, bots, and
deleted users (PLTFRM-2536)
- **Linear cycle/project tools swallowed GraphQL `errors[]`** —
`get-cycle`, `list-cycles`, `list-projects`, and `unarchive-project` now
surface GraphQL errors as `graphql_error` instead of failing schema
validation, including partial `data: { field: null }` responses.
`create-cycle` and `archive-cycle` pick up the upstream #704 errors[]
check by moving off the stale pin, and their inner mutation payloads
(`cycleCreate`, `cycleArchive`) are now nullable so partial-data error
responses also surface as `graphql_error` (PLTFRM-2537)
- **Fireflies transcript parsing failed on string `action_items`** —
`list-transcripts` and `get-transcript` accept `action_items` as an
array or a newline-joined string and normalize to each tool's output
contract (PLTFRM-2540)

New `TEMPLATE_PIN_OVERRIDES` entries point both providers at the PR head
commit (served directly by the upstream repo); fold back into
`TEMPLATE_SHA` once #708 merges. Fireflies keeps the same 2 pre-existing
skipped actions.

## Test plan

- [x] `pnpm --filter @mastra/connect test` — 17/17 files, 329 tests pass
- [x] `tsc --noEmit` clean
- [x] `audit-coverage.ts` — linear 46/46, fireflies 27/27 (100%)
- [x] `audit-shapes.mjs` — 0 findings
- [x] Upstream regression tests in #708 — including partial-data
coverage for all six cycle/project actions
- [x] Live smoke `--provider linear` (run `mastra-smoke-3e1792`) —
**PASS, 46/46 tools exercised**, including the fixed paths:
`archive_cycle` probe now surfaces "Linear GraphQL returned errors"
instead of a Zod crash
- [x] Live smoke `--provider fireflies` (run `mastra-smoke-3fb501`) —
the tools changed in this PR pass live: `list_transcripts` ✓,
`get_transcript` ✓

Fixes PLTFRM-2536, PLTFRM-2537, PLTFRM-2540.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## ELI5

This update fixes how the Linear and Fireflies tools handle responses
that can be missing information or use different formats. It also
updates the generated tools to use a newer version of their provider
templates.

## Changes

- Updated the Linear tools to accept nullable email fields and omit null
emails from attachment and project outputs.
- Updated Linear cycle and project tools to report GraphQL errors,
including responses that contain both partial data and errors.
- Updated Fireflies transcript tools to handle `action_items` returned
as either an array or a newline-separated string.
- Regenerated both provider toolsets and updated their template revision
pins.

## Validation

The supplied PR objectives report passing tests, type checking, coverage
audits, shape audits, and live smoke checks. These results were not
independently verified here.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-12 15:41:34 +01:00
arctic-char
8c05cd17d8
feat(connect): add search tools so agents stop paging full listings (#26271)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-07 14:47:13 -07:00
arctic-char
840d155d20
docs: @mastra/connect — platform integrations guide, quickstart, API + provider reference (#25863)
## Summary

Documentation for `@mastra/connect` and Mastra platform providers,
written against the current API on `main`. Replaces the stale closed PR
#23354 (written pre-`tools()` rename, before `channels()` existed).

### New pages

**Docs (platform sidebar, `Connect` category):**
- `/docs/mastra-platform/connect/overview` — what Connect is and the
getting-started path: connect a provider with the `mastra connect` CLI
(#25865), set the environment, wire `tools()` into a first agent
- `/docs/mastra-platform/connect/connections` — managing connections:
OAuth vs API-key auth, naming, multiple connections per provider,
re-auth, and the security model (server-held credentials, platform
proxy)
- `/docs/mastra-platform/connect/providers` — provider table (22 toolset
providers, 888 tools) with logos, the 9 hosted-MCP providers with links
to each provider's MCP docs, and setup walkthroughs for API-key
providers (Resend, PostHog, …)
- `/docs/mastra-platform/connect/tools` — `tools()` usage: scoping with
`integrations`/`allowTools`/`disallowTools`, per-request filtering with
a dynamic `tools` function and `requestContext`, connection pinning, MCP
providers, opt-in tool approval with `requireApproval` (#25740), and
call-time toolsets
- `/docs/mastra-platform/connect/channels` — `channels()` usage: wiring
into `new Mastra({ channels })`, per-channel credentials
(`slack-channels`, Telegram, Discord), provider options, and varying an
agent's toolset by channel via the `channel` request-context entry

**Reference:**
- `/reference/connect/tools` — `tools()` options tables, resolver
lifecycle (stale-while-revalidate cache,
`invalidate`/`refresh`/`disconnect`), connection resolution order,
`requireApproval` policy, error codes
- `/reference/connect/channels` — `channels()` options, `getRoutes()`,
per-provider overrides, reserved-field rejection
- `/reference/connect/credential` — `credential()` discriminated union
(`oauth2` / `api_key`), error codes
- `/reference/connect/providers` — generated per-tool reference for all
22 toolset providers, regenerated by
`docs/scripts/gen-connect-providers.mjs` (also added here)

Also adds the `ProviderLogo` component (theSVG-sourced marks with
light/dark mono tinting) and cross-links from `/docs/agents/tools` and
`/docs/channels`.

### Release scope

Matches what ships in v1:
- `environment()` is not documented — it isn't being released.
- Anthropic, Microsoft Teams, Stripe, and Twitter/X are excluded from
the provider docs and the generated reference.
- Reflects the `slack` → `slack-channels` split (#25332), the
`connect()` → `tools()` rename, and the `autoApproveTools` →
`requireApproval` approval model (#25740).

### Notes
- `reference/connect/providers.mdx` is generated from the provider tool
sources; rerun `node docs/scripts/gen-connect-providers.mjs .` when
providers are added or synced.

## Test plan
- [x] `pnpm validate` (666 files, sidebars sorted, all docs linked,
`new` tags within window)
- [x] `pnpm lint:remark` and `pnpm lint:prose` (Vale) — 0 errors
- [x] `pnpm format:mdx:check` — clean
- [x] Full production docs build — all pages compile; links and heading
anchors resolve (the only broken-anchor warnings are pre-existing on an
unrelated harness page)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds documentation that explains how to connect provider
accounts to Mastra and use them with agents and chat channels. It also
adds API references and a generated list of supported provider tools.

## Changes

- Added Connect guides for setup, connections, providers, tools, and
channels.
- Added API references for `tools()`, `channels()`, and `credential()`,
plus a generated reference for 22 provider toolsets.
- Added a `ProviderLogo` component and Connect entries in the
documentation sidebars.
- Added Connect links from the channels documentation. The follow-up
commit reverted the link from `/docs/agents/tools`.
- Moved the provider-reference generator to `packages/connect/scripts`
and added it to the package build task.
- Documented the v1 exclusions: `environment()`, Anthropic, Microsoft
Teams, Stripe, and Twitter/X.

## Validation

The author reports that `pnpm validate` passed for 666 files, `pnpm
lint:remark` and `pnpm lint:prose` reported no errors, and `pnpm
format:mdx:check` was clean. The author also reports that the production
docs build compiled all pages and resolved links and heading anchors,
with pre-existing broken-anchor warnings on an unrelated harness page.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: Justin Levine <20596508+jal-co@users.noreply.github.com>
Co-authored-by: Shane Thomas <shane@codekarate.com>
Co-authored-by: LekoArts <lekoarts@gmail.com>
2026-10-07 10:04:43 -04:00
arctic-char
04b7750404
feat(connect)!: rework the public API — providers option, glob filters, fail-fast validation (#26084)
## Summary

Reworks the `@mastra/connect` public API ahead of the first stable
release to make connect tools easier to attach to agents alongside
user-defined tools, to tighten configuration validation, and to shrink
the export surface. Breaking — the package has not shipped stable, so no
deprecation shims.

**Surface after this PR:** 6 value exports (`tools`, `channels`,
`credential`, `MastraConnectError`, `PROVIDERS`, `CHANNELS`) and 13
types. Every export maps to a documented concept.

## The new API, by example

### Basic usage — all connected providers, live

```ts
import { Agent } from '@mastra/core/agent';
import { tools } from '@mastra/connect';

const connectTools = tools({
  projectId: process.env.MASTRA_PROJECT_ID, // optional — this is the fallback
  ttlMs: 30_000, // default; 0 revalidates every resolution
});

const agent = new Agent({
  // ...name, instructions, model...
  // Mastra calls the resolver per generate/stream, so providers connected or
  // disconnected on the platform are reflected without a restart.
  tools: connectTools,
});
```

### Merging your own tools

The documented pattern is a plain dynamic `tools` callback — spread the
resolver's result alongside local tools (your tools win on key
collision):

```ts
const agent = new Agent({
  tools: async ctx => ({ ...(await connectTools(ctx)), weatherTool, searchTool }),
});
```

A `.with()` convenience method exists for the same merge as one
expression — `tools: connectTools.with({ weatherTool })` — accepting a
static record or a (sync/async, optionally context-reading) function,
with chaining and cache handles delegating to the base resolver. Docs
lead with the callback form; `.with()` stays as sugar.

### Choosing providers — two shapes

```ts
// Array — a real allowlist: ONLY these providers resolve, with default
// options. Anything else connected to the project is ignored.
tools({ providers: ['linear', 'resend'] });

// Record — per-provider configuration. Every connected provider resolves
// unless excluded:
tools({
  providers: {
    linear: true,                                      // enable with defaults (same as {})
    github: false,                                     // exclude, even if connected
    resend: { allowTools: ['resend_send_email'] },     // configure
    notion: { connectionId: 'conn_123' },              // pin one of several connections
  },
});
```

An enabled id that is neither a checked-in provider nor a platform
catalog integration fails with `invalid_options` — `channels()` throws
at call time against the shipped registry, `tools()` fails the
resolution once the catalog confirms the id is unknown. Excluded
(`false`) entries stay harmless no-ops; an unreachable catalog
downgrades to warn-and-skip.

### Filters and approval — with `*` globs

```ts
tools({
  providers: {
    // allowTools / disallowTools are mutually exclusive per provider.
    linear: { disallowTools: ['linear_delete_*', 'linear_archive_*'] },
    'google-mail': { allowTools: ['google-mail_list_*', 'google-mail_get_*'] },
    // requireApproval: true gates every tool; an array gates keys/globs.
    github: { requireApproval: ['github_create_*', 'github_merge_pull_request'] },
  },
});
```

Globs work on every path (checked-in HTTP tools, MCP discovery,
multi-connection wrappers). A per-provider glob that matches nothing
fails like an unknown literal name, so a typo never silently widens
access.

### Top-level defaults — one policy, per-provider opt-out

```ts
tools({
  // Applied to every provider that doesn't set its own filter/approval:
  disallowTools: ['*_delete_*'],
  requireApproval: ['*_send_*', '*_create_*'],
  providers: {
    linear: { requireApproval: false }, // opts out of the global policy
    resend: { allowTools: ['resend_send_email'] }, // own filter → skips BOTH defaults
  },
});
```

Per-provider options win wholesale. Top-level entries apply leniently —
the provider set is live, so an entry that matches nothing on one
provider simply doesn't apply there — and warn when they matched nothing
anywhere. Synthetic `<provider>__list_connections` wrappers are never
filtered or gated by defaults.

### Channels — same shapes

```ts
import { Mastra } from '@mastra/core';
import { channels } from '@mastra/connect';

const mastra = new Mastra({
  agents: { assistant },
  channels: await channels({
    providers: {
      discord: true,
      slack: { connectionId: 'conn_slack_prod' }, // alias for 'slack-channels'
      telegram: false,
    },
    // or an allowlist: providers: ['discord', 'slack']
  }),
});
```

Unknown channel ids throw synchronously at `channels()` time. `slack` is
accepted as an alias for the platform's `slack-channels` key (plain
`slack` names the Slack *tools* provider on the platform), so the common
spelling needs no quotes; it canonicalizes for registration and
connection lookup, and configuring both spellings throws.

### Resolver handles

```ts
const resolved = await connectTools();  // current flat tool record
await connectTools.refresh();           // force a platform fetch now (rejects on failure)
await connectTools.disconnect();        // close MCP transports + clear cache

const channelsResolver = await channels({ ... });
channelsResolver.getRoutes();           // webhook routes, synchronously, before any connection exists
```

Each handle covers a lifecycle moment the happy path (handing the
resolver to an agent / `new Mastra`) doesn't:

- **Calling the resolver directly** gives you the flat record outside an
agent — workflows invoking tools, scripts, tests, "what can my assistant
do" UI.
- **`refresh()`** is for the moments you *know* the world changed (your
UI's "Connect" button succeeded, a platform webhook fired, a test
provisioned a connection). The TTL cache is eventually consistent by
design (stale-while-revalidate); `refresh()` forces the fetch now and
rejects on failure, so you get a definite answer instead of polling
until TTL expiry or paying `ttlMs: 0` on every agent call.
- **`disconnect()`** releases owned resources — MCP providers hold live
client transports, and server shutdown / test teardown / dev hot-reload
need a way to close them without leaking handles.
- **`getRoutes()`** is synchronous and connection-independent because
webhook routes must mount at server boot while connections appear (and
disappear) on the platform afterwards. Provider instances are
constructed eagerly with no platform calls, so the route surface is
stable: a Slack connection added an hour after deploy hits a route that
was already mounted.

Freshness is governed by `ttlMs`; `refresh()` is the one explicit
action. There is no separate `invalidate()`.

### Considered and deferred: `channels().with(...)`

A channels-side `.with()` (merging self-managed `ChannelProvider`
instances into platform-managed resolution) was considered and
deliberately left out. Unlike tools — where every agent with local tools
hit the merge boilerplate — hybrid channel setups have no demonstrated
demand, and the method couldn't mirror tools' `.with()` anyway: channels
are instance-scoped with synchronous route mounting, so it could only
accept a static record, and route-path collisions would need throw
semantics rather than extras-win. Adding it later is a minor; shipping
it now is surface we may never need. If composition becomes common, an
array-accepting `new Mastra({ channels: [...] })` in core is likely the
better home.

## Breaking changes

- `integrations` option → `providers` on `tools()` and `channels()`;
types renamed (`ToolsProviderOptions`, `ChannelsProviders`,
`ChannelsProviderOptions`).
- `providers` array form is now a real allowlist (previously it
validated ids but resolved everything).
- Unknown enabled provider ids fail with `invalid_options` instead of
warning once and resolving nothing.
- Removed `connect()` (deprecated alias of `tools()`) and
`environment()`, with their tests and the now-unused
`resolveConnection()`.
- Removed the `TOOLS` registry alias (`PROVIDERS` is canonical) and the
`findRegistration`/`findChannelRegistration` helpers.
- Stopped exporting internal toolset plumbing (`defineProxyTool`,
`applyAllowTools`, `resolveConnectionId`, `ProxyToolConfig`,
`ProxyToolContext`, `ProviderToolsOptions`) — only generated providers
consume it, via relative imports, and no subpath exports exist to use it
with.
- Removed the `disabled: true` per-provider field; the `false` shorthand
is the one way to exclude a provider.
- Removed resolver `invalidate()` on both resolvers: `refresh()` forces
a fetch now and `ttlMs` governs freshness — one knob, one action.
- `MASTRA_<PROVIDER>_CONNECTION_ID` is no longer documented anywhere
(error messages, JSDoc, README now direct to the `connectionId` option).
The env fallback keeps working as an undocumented escape hatch.

The package README is rewritten for the new API.

## Test plan

- 305 unit tests pass (19 new across resolver, toolset, channels, MCP
discovery), including type-tests for the `providers` shapes and
`.with()` agent compatibility.
- `tsc --noEmit` clean (src + type-tests + smoke scripts), `build:lib`
clean, `oxlint`/`eslint` 0 warnings.
- Smoke-test harness drives the public `tools()`/`channels()` resolvers
and compiles against the new API.

## Follow-ups

- The connect docs (`docs/mastra-platform/connect/*`,
`reference/connect/*`) describe the pre-rework API and need a sync pass
once this merges.
- A live smoke run against a real project is recommended before the next
alpha publish.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## ELI5

This update changes how developers choose Connect providers and combine
their tools with their own. It also removes older setup methods so the
public API uses one consistent approach.

## Changes

- Replace `integrations` with `providers` in `tools()` and `channels()`.
Provider arrays act as allowlists; provider records support `true` and
`false` shorthands.
- Add `.with()` to combine Connect tools with local tools. Local tools
take precedence when names conflict. The README recommends a dynamic
`tools` callback for this pattern.
- Add `*` glob support and top-level tool-filter and approval defaults.
Per-provider options take precedence.
- Add `slack` as an alias for `slack-channels`. Configuring both names
is an error.
- Remove the `connect()` and `environment()` exports, related legacy
types, and resolver `invalidate()` methods. Keep the connection-ID
environment fallback, but direct users to configure `connectionId`.
- Update the README, changeset, tests, and smoke-test tooling for the
new API.

## Validation and follow-up

The PR description reports 305 passing unit tests, clean `tsc --noEmit`
and `build:lib` runs, and zero `oxlint` or `eslint` warnings. It also
notes a `tests: failing` label, recommends a live smoke run against a
real project, and says the Connect documentation still needs updating.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-06 12:05:44 -04:00
arctic-char
5054905e58
feat(connect): e2e smoke suite for channels() (#25987)
## Summary

Adds `smoke-test:channels`, an e2e smoke suite for the `channels()`
resolver — the channel-provider path (Slack, Discord, Telegram) that the
tools smoke suite (#25815) doesn't touch. Stacked on
`connect/e2e-smoke-tests`.

```bash
pnpm --filter @mastra/connect smoke-test:channels [--channel <id>] [--project-id <id>]
```

It verifies five layers against a live Platform project:

- **Resolver contract** — construction guards (missing project id,
invalid `ttlMs`), route mounting before any connection exists, TTL cache
+ `invalidate()`/`refresh()`, `disabled` overrides, and bogus
`connectionId` pins (warn-and-skip).
- **Server mount** — the resolver is handed to a real `Mastra` instance;
the suite asserts the channel routes land in the merged
`server.apiRoutes` with correct `requiresAuth` flags, mounts them
exactly the way the production server adapter does (`handler` /
`createHandler({ mastra })` onto Hono), and drives every platform's
webhook endpoint with real HTTP requests (unknown webhook ids answer
404).
- **Credential flow** — per connected channel: presence in the resolved
map (proves credential late-binding, e.g. Discord's `sync()` →
`configure()`), provider `id`/routes/`getInfo()`, a platform credential
fetch, and a vendor whoami call (Discord `GET /users/@me` +
`/applications/@me`, Slack `auth.test`, Telegram `getMe`). These
deliberately bypass the proxy — channel providers call vendor APIs
directly with the resolved token, so that direct path is what gets
smoked.
- **Discord full webhook flow** — the whole loop, end to end: the suite
overrides the provider's Ed25519 public key with a locally generated
pair (`providerOptions.publicKey`), `connect()`s an agent to a guild the
bot is already in (`commands: []`, so the guild is not mutated), POSTs a
**signed PING interaction** to the mounted route (200 PONG), POSTs a
forged signature (401), then `disconnect()`s and verifies the
installation is gone. Installations live in in-process channel storage,
so nothing persists after the run.
- **Slack manifest lifecycle** — `connect()` attempts a real
`apps.manifest.create` mint with the token the platform serves
(expecting a pending OAuth install + authorization URL), then
`disconnect()` deletes the minted app via `apps.manifest.delete`. Today
the `slack` integration serves a workspace bot token that Slack's
manifest API rejects (`not_allowed_token_type`), so the mint records a
**documented skip** — it still proves the manifest path is wired up to
Slack's token gate. Once the channel is rekeyed to the `slack-channels`
App Configuration integration (#25332), this exact flow runs the full
mint + delete lifecycle (a `TODO(#25332)` marks the integration-id list
for the rename).

### Companion fix: `@mastra/slack` `disconnect()` pending-app leak

`connect()` mints a real Slack app before the OAuth install completes,
but `disconnect()` only called `apps.manifest.delete` for **active**
installations — disconnecting during the pending window removed the
local record and orphaned the app in the Slack workspace. `disconnect()`
now deletes the minted app for pending installations too (unit-tested,
changeset included). This is also what keeps the smoke flow leak-free:
every app the suite mints is deleted in the same run.

Telegram's full flow needs `setWebhook` against the live bot plus a
public callback URL, and Slack event delivery needs a completed OAuth
install (pending installations are invisible to the events route by
design) — both out of scope; those webhook routes are still exercised
through the mounted server. The suite sends no messages and registers
nothing with any vendor beyond the Slack app it deletes in the same run.

`hono` is added as a devDependency (route mounting only); no
`@mastra/connect` runtime changes.

## Test plan

- Live run against the test project (`discord` + `slack` connected):
- `channels-resolver` 10/10, `server-mount` 5/5, `discord` 11/11 (incl.
full webhook flow), `slack` 6 pass + 1 documented skip (manifest token
gate, pending #25332), `telegram` skipped (no connection) — **0
failures**
- `@mastra/slack`: 92/92 tests (incl. new pending-disconnect deletes-app
test), `tsc --noEmit` clean
- `@mastra/connect`: `tsc --noEmit` clean (scripts included via
tsconfig), `vitest` 268/268, lint 0 warnings/errors
- Tools-suite audits unaffected: coverage 1014/1014, shape audit 0
findings

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-10-05 17:17:18 -04:00
arctic-char
529243e14d
feat(connect): add e2e smoke test suite for provider toolsets (#25815)
## Summary

Adds a live end-to-end smoke test suite for `@mastra/connect` covering
**all 26 checked-in providers at 100% tool coverage (1014 tool
invocations)**, plus the runtime fixes that running the suite live
surfaced.

### Smoke test harness (`packages/connect/scripts/smoke-test/`)

- `runner.ts` / `cli.ts` — reads `MASTRA_PLATFORM_SECRET_KEY` +
`MASTRA_PROJECT_ID`, resolves the project toolset through the public
`tools()` resolver, and runs per-provider scenarios. `pnpm --filter
@mastra/connect smoke-test [--provider <id>]`.
- `scenario.ts` — scenario interface + helpers (`makeStep`,
`requireTools`, `runReadBatch`, `probeTool`, `runId` tagging for
collision-free resource naming).
- 26 scenario files — each runs a self-contained `preflight → batch-read
→ create → read → update → delete` lifecycle through the tools
themselves (no backdoor cleanup). Cleanup is unconditional with
`log.error` on leaked resources.
- `audit-coverage.ts` — static audit: every shipped tool must appear in
its scenario (forward), and every scenario-referenced tool id must exist
(reverse). Exits non-zero on unknown ids.
- `audit-shapes.mjs` — static input-shape audit: cross-checks scenario
`call()` payloads against each tool's zod input schema, flagging unknown
keys (silently stripped) and missing required keys. Exits non-zero on
findings.
- `scripts/smoke-test/**` is now included in the package tsconfig, so
`tsc --noEmit` covers it.

### Runtime changes surfaced by live runs

- **`MastraConnectError.response.status` alias** — generated provider
tools come from upstream Nango templates whose error handlers check the
axios-shaped `error.response?.status` (35 generated files). The alias
makes those handlers work unchanged (e.g. the expected-404 recovery path
in `github_create_or_update_file`), instead of hand-editing generated
code that the next `sync-templates` run would erase. Unit tested.
- **`extractProblemDetail`** — now also extracts the first
human-readable message from `{ errors: [{ message, long_message }] }`
payloads (Clerk, Nango v2), preferring `long_message`. Unit tested (10
new tests in `errors.test.ts`).
- **Clerk provider regenerated** from the upstream template fix
(NangoHQ/integration-templates#670). Breaking tool-contract changes
(documented in the changeset):
- `clerk_list_sessions` requires `client_id` or `user_id` and no longer
returns `total`.
- `clerk_create_user` requires at least one identifier via schema
refine.
  - `clerk_list_users` issues a count request to populate `total`.

### Policy / docs

- `packages/connect/AGENTS.md` — package guidance including the
new-provider checklist: every new provider must ship a scenario with
100% tool coverage.
- `.coderabbit.yaml` — path instructions enforcing the scenario
checklist on `packages/connect/src/providers/**` PRs.

## Test plan

- `pnpm --filter @mastra/connect test` — 267/267 pass (vitest + `tsc
--noEmit`, now covering the smoke scripts)
- `pnpm --filter @mastra/connect lint` — clean
- `tsx packages/connect/scripts/smoke-test/audit-coverage.ts` —
1014/1014 tools (100%) across 26 providers, 0 unknown ids
- `node packages/connect/scripts/smoke-test/audit-shapes.mjs .` — 0
findings
- Live runs against a real platform project: all 26 providers exercised;
highlights: github 42/42, supabase 27/27, google-docs 36/36, hubspot
44/44, google-mail 50/52 (2 steps blocked on upstream
NangoHQ/integration-templates#704), google-analytics 11/11


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds a command that checks whether connected-service tools work
in a test project. It also updates Clerk tools to match API changes and
improves how the package reports API errors.

## Summary

- Add a smoke-test runner, CLI, report output, and scenarios for all 26
checked-in providers. The runner resolves tools through the public
`tools()` resolver.
- Add static audits for tool coverage and input shapes. Document how to
run the suite and add provider scenarios.
- Update Clerk tool schemas and behavior, including stricter input
checks, revised session listing, and user-list filters and counts.
- Add `response.status` to `MastraConnectError` and extend
`extractProblemDetail` to read messages from `errors` arrays.
- Add error tests and include smoke-test scripts in the TypeScript
project.

## Verification

The supplied context reports 267/267 tests passing, clean lint,
1,014/1,014 tools covered, and no shape-audit findings. These results
are author-reported. Live runs reportedly exercised all 26 providers;
two Google Mail steps were blocked by an upstream issue.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastracode <mastracode@users.noreply.github.com>
2026-10-05 17:05:36 -04:00
arctic-char
a711df35e3
feat(connect): add Google Docs, Drive, Sheets toolsets and support binary responseType (#25596)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-09-30 11:59:49 -07:00
arctic-char
9e7734f0ed
feat(connect): route agent tools across multiple provider connections (#24864)
Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
2026-09-29 09:44:25 -07:00
Rhys Balevicius
2d9518abee
refactor(factory): discover Platform GitLab connections on the gitlab integration only (#24686) 2026-09-22 14:42:59 -07:00
arctic-char
510d86ace3
feat(connect): 10 generated providers for internal-agents migration (Slack, GitHub, Google, Fireflies, PostHog, Stripe, Discord, X, HubSpot) (#24606)
## Summary

Adds 10 generated providers to `@mastra/connect` — **Slack, GitHub,
Google Mail, Google Calendar, Fireflies, PostHog, Stripe, Discord,
Twitter/X, HubSpot** — 456 checked-in tools total, taking the registry
from 11 to 21 providers. This covers every integration our internal
agents currently hand-roll (Slack in 8 apps, GitHub in 4, Google
Workspace in 3, Fireflies/PostHog in 2 each, plus Stripe, Discord, X),
so those apps can migrate to `connect()` toolsets.

**Stacked on** `feat/connect-template-runtime-support`
(`zodValidateInput` + `getConnectionWithCredentials` runtime support
these tools generate against). Review that PR first.

### Template provenance

All 10 providers pin the
[NangoHQ/integration-templates#677](https://github.com/NangoHQ/integration-templates/pull/677)
contribution branch (`arctic-char/integration-templates@c3091db1`) —
upstream main plus agent-focused gap actions: PostHog HogQL `run-query`,
Stripe balance/dispute/coupon/account reads, GitHub
`list-tags`/`get-tree`, Slack `invite-shared`, Twitter
`search-tweets`/`list-following`, HubSpot `submit-form`. Once #677
merges upstream, the shared `PIN_677` override is dropped and providers
regenerate from the upstream pin.

### Reviewing generated code

~53k of the ~53k inserted lines are machine-emitted. The hand-written
surface in this PR is small: `templates-config.ts` pins, registry test
(11 → 22 providers), README/NOTICE provenance, changeset. To verify the
generated output is reproducible, re-run `pnpm --filter @mastra/connect
sync-templates && add-provider <name> --yes` per provider and confirm a
clean diff; manifests record source repo, commit, and per-file
checksums. Skipped actions (streaming, inline schemas, one upstream type
bug) are listed with reasons in each provider's manifest.

## Test plan

- `pnpm --filter @mastra/connect test` — 171/171 (registry test asserts
all 22 providers).
- `pnpm --filter @mastra/connect build:lib` and `lint` — clean.
- Grep audit of generated code: only expected imports
(`@mastra/core/tools`, `zod`, platform-proxy types); no credential reads
outside the one rewritten `whoami` action, no env/network primitives.

---------

Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
2026-09-22 14:48:10 -04:00
arctic-char
cdd7ead1b3
feat(connect): runtime + generator support for credential and validation template patterns (#24605)
Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
2026-09-22 11:02:54 -07:00
arctic-char
99b94b87f5
feat(connect): add generated Snowflake tools (#24066)
## Summary

- add 15 generated Snowflake tools registered under the OAuth
`snowflake` integration ID: SQL statement execution with async polling,
status, results, and cancellation, plus read-only listings for
warehouses, databases, schemas, tables, columns, views, stages, streams,
tasks, roles, and users
- generated from the upstream `snowflake-jwt` templates with
`add-provider snowflake-jwt --as snowflake` — the Snowflake SQL API
calls are identical for both auth modes, so the same templates serve
OAuth connections
- fix the generator to rewrite helper parameters typed inline as
`Parameters<(typeof action)['exec']>[0]` to `PlatformProxy`; the
stripped `createAction` declaration previously left the `list-roles`
template's generated module referencing a name that no longer exists

## Security note

`snowflake_execute_statement` submits arbitrary SQL, bounded only by the
grants of the Snowflake role attached to the connection. Scope connected
users to least privilege, or restrict the toolset with `allowTools`.

## Test plan

- `pnpm --filter @mastra/connect test` — 152 tests pass, including a new
generator test covering the inline context-type rewrite
- `pnpm --filter @mastra/connect lint` and `build:lib` pass
- generated diff reviewed as vendored code per `scripts/README.md`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds ready-to-use Jira and Snowflake tools to `@mastra/connect`.
They let applications manage Jira data and run Snowflake queries through
OAuth connections, while handling authentication, retries, polling, and
response validation.

## Summary

- Added 15 generated Snowflake tools for SQL execution, statement
polling, cancellation, and resource listings.
- Added 37 generated Jira tools for issues, comments, worklogs,
projects, users, metadata, transitions, and search.
- Registered both providers with OAuth integration IDs and connection
environment variables.
- Improved `PlatformProxy` with:
  - Provider HTTP status propagation, including `202`.
  - Shared metadata updates through `updateMetadata`.
  - Template-facing connection and metadata types.
- Updated provider generation to rewrite inline helper contexts to
`PlatformProxy`.
- Added manifests, generated-tool fixtures, registry coverage, and
proxy/client tests.
- Added changesets for the Jira and Snowflake providers.

All reported tests, linting, and builds pass.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
2026-09-16 13:35:59 -04:00
Rhys Balevicius
f81e987e46
feat(connect): add generated Resend and incident.io tools (#23631)
## Summary

- add 80 generated Resend tools for email operations, domains,
templates, audiences, contacts, broadcasts, webhooks, and related
account resources
- add 66 generated incident.io tools for incidents, alerts, actions,
follow-ups, timelines, on-call data, teams, users, postmortems, and
catalog reads
- pin each pending provider to its own template repository and commit
while the templates are under review upstream, keeping the shared pin on
NangoHQ/integration-templates
- strip webhook signing secrets from generated Resend tool results
- pass pre-encoded request bodies through the connection proxy
unchanged, which the multipart contact import needs

`@mastra/connect` depends on tool definitions checked into each release,
which left Resend and incident.io unavailable. The tools are generated
from provider contracts and run through the Platform connection proxy,
so provider credentials stay in the platform connection.
Catalog-discovered MCP integrations are a separate change stacked on
this one.

This PR is stacked on #23527 (`feat/connect-provider-catalog`). The
generated contracts come from
[NangoHQ/integration-templates#667](https://github.com/NangoHQ/integration-templates/pull/667)
and
[NangoHQ/integration-templates#668](https://github.com/NangoHQ/integration-templates/pull/668),
pinned by immutable commit in each provider manifest.

## Test plan

- `pnpm --filter @mastra/connect test` — 11 files, 150 tests passed
- `pnpm --filter @mastra/connect lint`
- `pnpm --filter @mastra/connect exec tsc --noEmit`
- generated manifests contain 80 Resend tools and 66 incident.io tools
with zero skipped actions
- every generated tool executes through the authenticated connection
proxy against the template fixtures
- Resend read path validated against a local Platform gateway with a
live Resend connection


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds ready-to-use tools for Resend and incident.io. The tools
use Mastra Platform connections, so provider credentials remain in the
platform.

## Summary

- Added 80 generated Resend tools and 66 generated incident.io tools.
- Covered email, domains, contacts, audiences, broadcasts, templates,
webhooks, incidents, alerts, schedules, on-call data, teams, users,
postmortems, and catalog resources.
- Registered both providers with connection ID environment variables and
`allowTools` filtering.
- Added provider manifests with template repository, commit, generation
metadata, and file hashes.
- Added provider-specific immutable template pins.
- Redacted Resend webhook `signing_secret` values from results and
output schemas.
- Preserved pre-encoded string request bodies for multipart contact
imports.
- Added fixtures and tests for proxy requests, authentication,
validation, pagination, filtering, and secret redaction.
- Updated package and maintainer documentation.
- Test, lint, and TypeScript results are reported as passing.
- Review finding counts are unavailable from the supplied information.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-09-15 15:27:34 -04:00
arctic-char
0d3186f8bd
feat(connect): add the generated provider catalog (#23527)
## Summary

Adds the first consolidated provider catalog for `@mastra/connect`,
built on the connection runtime introduced in #23087.

- Ships 237 generated tools across seven providers:
  - Linear: 46
  - Anthropic: 12
  - Notion: 44
  - OpenAI: 26
  - Supabase: 27
  - Clerk: 42
  - WorkOS: 40
- Adds safe connection configuration and metadata access for tools that
need connection-specific provider origins.
- Forwards provider base URL overrides and repeated query parameters
through the platform proxy.
- Converts OpenAI generated-image output into model-native multimodal
content so base64 data does not consume the text context window.
- Renders generated tool images in Studio chat.
- Silently skips providers without a matching project connection while
retaining warnings for actionable connection problems.

Generated provider manifests record their source template commit,
skipped actions, and file checksums. Actions requiring unsupported proxy
behavior remain excluded.

Paired platform support for connection context and constrained base URL
overrides is tracked in mastra-ai/platform#2721.

## Test plan

- `@mastra/connect`: 9 test files, 119 tests passed
- Playground generated-image rendering: 56 tests passed
- Playground UI tool metadata extraction: 8 tests passed
- `@mastra/connect` lint and production build passed
- Playground and Playground UI typechecks and production builds passed
- Targeted lint and Prettier checks passed for all changed frontend
files

---------

Co-authored-by: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>
2026-09-15 13:03:39 -04:00
arctic-char
c2f13279f1
feat(connect): add @mastra/connect runtime and provider generator (#23087)
Adds the provider-agnostic `@mastra/connect` runtime and the maintainer
toolchain used to generate provider toolsets from the pinned
`NangoHQ/integration-templates` catalog.

## What this PR includes

### Runtime

- `connect(options?)`: a live, TTL-cached resolver for project
integration toolsets, with stale-while-revalidate behavior,
deterministic connection selection, per-provider failure isolation, and
`invalidate()` / `refresh()` controls.
- `credential(connectionId)`: raw credential retrieval for SDKs and
other interactions that cannot use generated proxy tools.
- A Nango-compatible action shim that runs vendored action bodies
through Mastra's integrations proxy instead of Nango Actions or
`nango.proxy()`.
- Provider registration and filtering infrastructure used by generated
provider modules.

### Maintainer provider workflow

- Pins the upstream template catalog to an exact commit and syncs it
into the gitignored `packages/connect/.templates/` directory.
- Generates one module per action, exporting only
`<actionName>InputSchema` and `<actionName>OutputSchema`; helper schemas
stay private to the action module.
- Adds maintainer-only `add-provider`, `remove-provider`, and
`list-providers` commands.
- Supports `add-provider <providerId> --as <integrationId>`,
manifest/checksum-based hand-edit detection, overwrite confirmation,
collision rejection, deterministic registry updates, and provider
removal confirmation.
- Records the upstream template commit and generated-file checksums in
each provider manifest.
- Includes an ELv2 third-party notice for source adapted from
`NangoHQ/integration-templates`.

### Docs

- Documents `connect()`, `credential()`, runtime connection discovery,
and the generated-provider architecture.
- Removes the old hand-written per-provider builder references.

## Provider PR stack

This base PR intentionally contains **no generated provider
implementation**. Its shipped provider registry is empty. Generated
providers are added in separate PRs stacked on this branch so their
generated source and tool surface can be reviewed independently.

## Test plan

- `pnpm --filter @mastra/connect test` — 84 tests passing
- `pnpm --filter @mastra/connect lint` — 0 warnings/errors
- `pnpm --filter @mastra/connect build:lib` — ESM and CJS builds passing
- `pnpm --dir docs validate` — frontmatter and sidebar validation
passing
- `npm pack --dry-run` — verifies `NOTICE.md` is included in the
published package


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds `@mastra/connect`, which helps agents find integrations,
use their credentials, and call provider actions through a platform
proxy. It also gives maintainers tools to generate and manage provider
tools.

## What changed

- Added `connect()` with TTL caching, stale-while-revalidate refresh,
manual cache controls, deterministic connection selection, provider
filtering, tool allowlists, and per-provider failure isolation.
- Changed `connect()` to return a flat `ToolsInput` structure for direct
use with Agent tools.
- Added `credential()` for raw credential retrieval.
- Added a typed integrations client with response validation, error
handling, token redaction, and secure path validation.
- Added platform-proxy support with lazy connection validation, typed
action errors, and retries for idempotent requests.
- Added provider registration and lookup APIs.
- Added workflows to sync pinned templates, generate tools and schemas,
record manifests and checksums, manage providers, and detect modified or
corrupt generated files.
- Preserved the `MASTRA_<PROVIDER>_CONNECTION_ID` environment-variable
convention.
- Added ELv2 licensing and third-party attribution.
- Added runtime, generator, registry, client, proxy, and
provider-command tests.
- Added package build, lint, test, and publishing configuration.

The shipped provider registry is intentionally empty. Providers can be
added through separate maintainer changes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Mastra Code (openai/gpt-5.6-sol) <noreply@mastra.ai>
2026-09-14 14:09:48 -04:00