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

5 commits

Author SHA1 Message Date
mastra-platform[bot]
6e178c365a
docs: declare node types in tsconfig examples (#27974) 2026-10-21 11:51:24 +02:00
YujohnNattrass
edbc4c9bff
fix(template-agent-builder): require only a single OpenAI API key (#18188)
Co-authored-by: YJ <yj@example.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>
Co-authored-by: Marvin Frachet <marvin@mastra.ai>
2026-06-19 11:09:11 +02:00
YujohnNattrass
1a8b1dc3cf
Show tool provider Connect button in Agent Builder when authentication is disabled (#18180)
## Summary

In the Agent Builder tools picker, the **Connect** button for Composio
(and other tool provider) toolkits did not appear when a project runs
without authentication. The picker showed the toolkit row (e.g. Gmail)
but the connection control next to it was stuck on a loading
placeholder, so authors could never start the OAuth connect flow.

The root cause is that the picker's connection lookups are
"self-scoped": they wait for a signed-in user so that admins only ever
see their own connections. In a project with authentication turned off
there is no signed-in user, so that wait never resolved and the
connection query stayed disabled forever — leaving the control
permanently in its loading state.

This change makes the self-scoped lookups wait for the current-user
query to **settle** instead of requiring it to return a user. When
authentication is off, the query settles with no user, the explicit
per-user filter is omitted, and the server scopes results by the request
context as it already does. As a result, existing connections load and
the Connect button appears whether or not authentication is configured.
Behavior for authenticated/admin users is unchanged — they still only
see their own connections.

It also defaults the Agent Builder template's Composio provider to the
`gmail` toolkit, so a freshly scaffolded template has a connectable
toolkit available in the picker out of the box.

## Changes

- `use-existing-connections.ts` / `use-all-connections.ts`: gate
self-scoped connection queries on the current-user query having settled
rather than on it producing a user id.
- `template-agent-builder`: default the Composio provider to the `gmail`
toolkit.
- Added regression tests for both hooks covering the authenticated and
auth-disabled paths.
- Added a changeset.

## Test plan

- `pnpm --filter ./packages/playground test run` for the tool-providers
+ agent-builder suites — 121 passing, including new auth-disabled
regression tests for both hooks.
- `pnpm --filter ./packages/playground typecheck` — clean.
- `eslint` on the changed files — clean.
- Manual: run the Agent Builder template/example with authentication
disabled and confirm the Connect button appears for the Gmail toolkit
and OAuth can be started.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The **Connect** button in the tools picker waits for the app to figure
out “who is the current user.” If authentication is turned off, that
“who am I?” check doesn’t return a user ID—so the picker waits forever
and never shows **Connect**. This PR makes the picker wait only until
that check is finished, even when there isn’t a signed-in user.

---

## Overview
This PR fixes a bug in Mastra Agent Builder’s tool provider toolkit
picker (e.g., **Composio**) where the **Connect** button failed to
appear when authentication is disabled.

## Root cause
Connection lookup hooks self-scoped their requests to a signed-in user
by gating on a resolved current user / user ID. In auth-disabled
projects, there is no signed-in user, so the current-user lookup never
provided an ID and the connection query stayed stuck (disabled/loading),
preventing **Connect** from appearing.

## Fix
### Wait for the “current user” query to settle (not for a user ID)
- Updated `use-existing-connections.ts` and `use-all-connections.ts` to
gate self-scoped connection queries on the **settling** of
`useCurrentUser` rather than requiring a truthy `callerAuthorId`.
- When authentication is disabled and `/api/auth/me` indicates
**unauthenticated (401)**, the hooks proceed while omitting the per-user
`authorId` filter; server/context scoping still ensures the correct
connections are returned.
- For authenticated users, behavior remains unchanged: users only see
their own connections.

### Typed unauthenticated detection + “fail closed”
- Enhanced `use-current-user.ts` to throw a typed `CurrentUserError` and
added `isUnauthenticatedError()` to specifically detect `401` outcomes.
- Added regression coverage to ensure:
- **401** allows the connection query to complete and
`hasConnection('composio', 'gmail')` remains `true` as expected.
- Non-401 errors (e.g., **500**) are handled **fail-closed**
(connections handler not called; hook remains without results).

## Additional changes
- **Template update:** The Agent Builder template’s Composio provider
now defaults to the `gmail` toolkit (`allowedToolkits: ['gmail']`) so
new scaffolds have a connectable toolkit available.
- **Regression tests:** Added/extended tests for both authenticated and
auth-disabled (401) scenarios, plus non-401 “fail closed” behavior.
- **Changeset:** Added a changeset entry documenting the fix.

## Testing
Confirmed passing tests (121 total), including the new regression
coverage, with clean type checking and linting.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: YJ <yj@example.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>
2026-06-18 17:06:44 -07:00
YujohnNattrass
f79daa298f
feat(template-agent-builder): make WorkOS auth and EE license optional in dev (#18171)
## Summary

The Agent Builder template could not start unless WorkOS auth
credentials and a `MASTRA_EE_LICENSE` were both set, which made it hard
to try the template locally. This change makes both optional for local
development so the template boots out of the box.

- **Auth is now optional.** WorkOS AuthKit + RBAC follow the same
env-gated pattern already used for the Composio, Slack, and Browserbase
integrations: they are only enabled when the WorkOS variables are
present. With them unset, the template runs without authentication.
- **The redundant startup license check is removed.** The license is
still enforced by `@mastra/editor` for production use (with a
development bypass), so the template's own fail-fast guard was redundant
and blocked local dev. Development no longer requires a license.

## Changes

- `src/mastra/auth.ts`: `initWorkOS` returns `null` when the WorkOS env
vars are not all set, instead of throwing.
- `src/mastra/index.ts`: `auth`/`rbac` are spread into the server config
only when WorkOS is configured; removed the `requireEnterpriseLicense()`
startup call.
- `src/mastra/env.ts`: removed the now-unused `requireEnterpriseLicense`
and `requiredEnv` helpers.
- `.env.example`: WorkOS moved to an optional section; license
documented as required for production only.
- `README.md`: WorkOS listed under optional integrations; license framed
as production-only with a dev note.

## Test plan

- Copy the template out of the monorepo, `pnpm install`, set only
`OPENAI_API_KEY`, run `mastra dev` — it boots with no auth and no
license.
- Add `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_COOKIE_PASSWORD` and
restart — auth + RBAC are enabled.

## Note

This PR is based on the playground request-context fix branch so its
diff is scoped to the template only. Rebase onto `main` once that PR
merges.


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

## ELI5 (Explain Like I'm 5)

This PR makes it possible to run the Agent Builder template on your
computer without needing to set up special authentication or buy an
enterprise license first. Instead of requiring all the setup details
before you can even start the app, it now checks if you have them and
skips authentication if you don't, letting you test and develop locally
with just the OpenAI API key.

## Changes Summary

### Core Functionality Changes

**Authentication made optional for local development:**
- `src/mastra/auth.ts`: The `initWorkOS` function now returns `null`
when WorkOS environment variables (`WORKOS_API_KEY`, `WORKOS_CLIENT_ID`,
`WORKOS_COOKIE_PASSWORD`) are missing, instead of throwing an error.
When variables are present, it initializes WorkOS auth and RBAC as
before.
- `src/mastra/index.ts`: The Mastra server configuration now
conditionally includes `auth` and `rbac` only when WorkOS is properly
configured. Removed the unconditional `requireEnterpriseLicense()`
startup-time check.
- `src/mastra/env.ts`: Removed the `requiredEnv` and
`requireEnterpriseLicense` helper functions that are no longer needed
with the optional authentication pattern.

### Configuration & Documentation Updates

**Updated environment variable documentation:**
- `.env.example`: Clarified that `OPENAI_API_KEY` powers builder-created
agents and that `MASTRA_EE_LICENSE` is required only for production
(development runs without it). Expanded WorkOS section to explain that
AuthKit + RBAC are only enabled when all required WorkOS variables are
set.
- `README.md`: Updated to reflect that WorkOS AuthKit
authentication/RBAC is optional, adjusted license prerequisites for
production vs. development, and documented that the template runs
without authentication when WorkOS values are unset.

### Model & Dependency Updates

**Model configuration:**
- `src/mastra/index.ts`: Updated the builder model allowlist to use the
`gpt-5.4-*` family with `gpt-5.4-nano` as the default model. Removed
redundant builder features configuration block.

**New dependencies:**
- `package.json`: Added `@mastra/stagehand: "latest"` and `zod:
"^4.3.6"` as direct dependencies (zod was previously relied upon as a
peer of `@mastra/core`).

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

---------

Co-authored-by: YJ <yj@example.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>
2026-06-18 14:54:40 -07:00
Marvin Frachet
b16814bea8
feat: add agent builder template (#17759)
## Summary
- Add a setup-only Agent Builder template under
`templates/template-agent-builder`.
- Fail fast when `MASTRA_EE_LICENSE` is missing or too short.
- Wire WorkOS AuthKit and WorkOS-backed RBAC permissions into the
template server config.
- Register optional Composio, Slack, and Browserbase/Stagehand
integrations only when their env vars are configured.
- Document that the default local filesystem workspace does not require
Git credentials.

## Test plan
- `pnpm install --no-frozen-lockfile --config.strict-dep-builds=false`
- `pnpm exec tsc --noEmit`
- `pnpm build`
- `node .mastra/output/index.mjs` without env fails on missing
`MASTRA_EE_LICENSE`
- `MASTRA_EE_LICENSE=12345678901234567890123456789012 node
.mastra/output/index.mjs` fails next on missing `WORKOS_API_KEY`


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

## ELI5

This PR adds a ready-to-use "Agent Builder" template for Mastra that
includes enterprise security (license validation), user management
(WorkOS authentication and permissions), and optional integrations
(Slack, Composio, Browserbase). It's a quickstart recipe for building AI
agents with enterprise features pre-configured.

## Changes Overview

This PR introduces a complete CLI-installable Agent Builder template at
`templates/template-agent-builder` with the following structure and
behavior:

### Configuration & Setup Files

**Environment Configuration** (`.env.example`):
- Defines required variables: `MASTRA_EE_LICENSE` and `OPENAI_API_KEY`
- Configures WorkOS AuthKit + RBAC: `WORKOS_API_KEY`,
`WORKOS_CLIENT_ID`, `WORKOS_COOKIE_PASSWORD`, `WORKOS_REDIRECT_URI`
- Optional provider settings with conditional enablement: Composio,
Slack (editor channel wiring), and Browserbase/Stagehand

**Project Configuration**:
- `package.json`: Configures the agent-builder package with Mastra
dependencies, `@ai-sdk/openai`, Node 22.13.0+ requirement, and
build/dev/start scripts
- `pnpm-workspace.yaml`: Workspace configuration allowing builds for
specific dependencies (`@google/genai`, `bufferutil`, `esbuild`,
`protobufjs`)
- `tsconfig.json`: TypeScript configuration targeting ES2022 with strict
type-checking and no output emission
- `.gitignore`: Excludes generated artifacts, environment files,
`.mastra` directory, SQLite databases, and platform config files

**Documentation** (`README.md`):
- Explains Agent Builder features (enabled builder, WorkOS AuthKit +
RBAC, local filesystem workspace, observational memory)
- Lists prerequisites and step-by-step quickstart
- Clarifies that Git credentials are not required for the default local
filesystem setup
- Documents optional integrations that conditionally register based on
environment variables

### Core Implementation

**License & Environment Management** (`src/mastra/env.ts`):
- `getEnv()`: Reads and trims environment variables
- `hasEnv()`: Tests presence of non-empty values
- `requiredEnv()`: Throws descriptive errors for missing required
variables
- `requireEnterpriseLicense()`: Validates `MASTRA_EE_LICENSE` exists and
has at least 32 characters

**WorkOS Authentication** (`src/mastra/auth.ts`):
- `initWorkOS()`: Validates WorkOS environment variables and constructs
both `MastraAuthWorkos` and `MastraRBACWorkos` instances
- Configures RBAC with role-to-permissions mapping: admin/superadmin
(wildcard access), member/operator/viewer/auditor (scoped permissions)
- Sets 1ms cache TTL for RBAC provider

**Workspace Configuration** (`src/mastra/workspace.ts`):
- Exports a `Workspace` instance (`builder-workspace`) backed by local
filesystem at `.mastra/workspace`

**Main Template Entry Point** (`src/mastra/index.ts`):
- Fails fast on missing `MASTRA_EE_LICENSE` using top-level await
- Initializes LibSQL-backed storage (`mastra.db`)
- Conditionally registers integrations:
  - Composio tool providers (when `COMPOSIO_API_KEY` set)
  - Slack editor channel wiring (when Slack env vars present)
- Stagehand/Browserbase browser setup (when Browserbase credentials
configured)
- Configures `MastraEditor` with agent-related feature flags (tools,
agents, workflows, favorites, skills, model, optional browser + avatar
upload)
- Creates and exports the `mastra` instance with WorkOS
authentication/RBAC, storage, workspace, builder agent, sourcemaps,
Swagger UI, and observability (fixed service name with sensitive-data
filtering)

## Test Coverage

PR includes label noting "tests: no tests added."

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

---------

Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
2026-06-11 09:12:56 +02:00