@mastra/connect 0.3.1 → 0.4.0

package/README.md

@@ -62,6 +62,28 @@ Resend requires a verified sending domain and a key authorized for the operation
 
 List tools return one provider page and preserve its response envelope. When `next_cursor` is present, pass it as `after` for Resend and incident.io. Preserve filters and sort options between pages.
 
+### Sandbox environment
+
+Some agents run inside a sandbox that shells out to CLIs (git, `gh`) or needs provider tokens in the process environment. `environment()` materializes those credentials from the same project connections `connect()` uses, so an agent that already has GitHub attached needs no separate credential wiring.
+
+```ts
+import { environment } from '@mastra/connect';
+
+const env = environment({
+  projectId: process.env.MASTRA_PROJECT_ID,
+  client: { accessToken: process.env.MASTRA_PLATFORM_ACCESS_TOKEN },
+});
+
+const { env: envVars, onStart } = await env();
+
+await sandbox.start({
+  env: envVars, // GH_TOKEN, GITHUB_TOKEN, …
+  onStart, // runs `git config --global credential.https://github.com.helper …`
+});
+```
+
+`environment()` mirrors `connect()`: same `projectId`, `client`, and per-provider `integrations` overrides (`connectionId` to pin, `disabled: true` to exclude). GitHub is the first provider with an env contributor — its OAuth token is exported as `GH_TOKEN`/`GITHUB_TOKEN` so both `gh` and `git` HTTPS operations authenticate as the connected user, and `onStart` wires a git credential helper that reads the token from the environment rather than baking it into git config.
+
 ### Template provenance
 
 Resend and incident.io are generated from integration-template contributions [#667](https://github.com/NangoHQ/integration-templates/pull/667) and [#668](https://github.com/NangoHQ/integration-templates/pull/668). Slack, GitHub, Google Mail, Google Calendar, Fireflies, PostHog, Stripe, Discord, Twitter/X, and HubSpot are generated from contribution [#677](https://github.com/NangoHQ/integration-templates/pull/677), which adds agent-focused actions (PostHog HogQL queries, Stripe balance/dispute/coupon/account reads, GitHub tags and trees, Slack Connect invites, Twitter search and following, HubSpot form submission) on top of upstream main. Until they land upstream, each provider manifest pins the contributing repository and exact commit and records generated file checksums.

package/dist/channels.d.ts

@@ -0,0 +1,127 @@
+import type { ChannelProvider } from '@mastra/core/channels';
+import type { ConnectClientOptions } from './client.js';
+import type { DiscordReservedProviderOption, SlackReservedProviderOption, TelegramReservedProviderOption } from './providers/channels.js';
+/**
+ * `providerOptions` fields that `channels()` refuses to forward to a
+ * `ChannelProvider` constructor. Marking them `never` here makes the compiler
+ * reject them at the call site; the resolver also strips them at runtime with
+ * a warning as a defensive layer.
+ *
+ * Two categories, applied per integration:
+ *
+ * - **Credentials.** The whole point of `channels()` is that the credential
+ *   comes from the platform connection. Passing another `refreshToken` /
+ *   `botToken` via `providerOptions` would silently override the connection
+ *   (and thereby bypass rotation, revocation, and auditing).
+ * - **Framework-managed.** `baseUrl` is derived from the Mastra server config
+ *   so webhook URLs match the actually-bound host. `encryptionKey` is a
+ *   process-wide at-rest secret sourced from `MASTRA_ENCRYPTION_KEY`; letting
+ *   `providerOptions` override it per integration would fragment the
+ *   encryption boundary.
+ */
+type ForbidReservedOptions<Reserved extends string> = {
+    [K in Reserved]?: never;
+};
+/** Per-integration `providerOptions` shapes with reserved fields disallowed. */
+export type SlackChannelsProviderOptions = Record<string, unknown> & ForbidReservedOptions<SlackReservedProviderOption>;
+export type TelegramChannelsProviderOptions = Record<string, unknown> & ForbidReservedOptions<TelegramReservedProviderOption>;
+export type DiscordChannelsProviderOptions = Record<string, unknown> & {
+    applicationId?: string;
+    publicKey?: string;
+} & ForbidReservedOptions<DiscordReservedProviderOption>;
+/** Base shape shared by every integration override; per-id specializations narrow `providerOptions`. */
+export interface ChannelsIntegrationOptions<ProviderOptions = Record<string, unknown>> {
+    /** Pin a specific connection id (bypasses single-active-connection resolution). */
+    connectionId?: string;
+    /** Exclude this provider entirely, even if a connection exists. */
+    disabled?: boolean;
+    /** Provider-specific options merged into the second argument of `ChannelProviderRegistration.build()`. */
+    providerOptions?: ProviderOptions;
+}
+/**
+ * Integration overrides map, typed per known channel id. Unknown ids are
+ * allowed with a generic option shape so future channels don't need a type
+ * change here.
+ */
+export interface ChannelsIntegrationOverrides {
+    slack?: ChannelsIntegrationOptions<SlackChannelsProviderOptions>;
+    telegram?: ChannelsIntegrationOptions<TelegramChannelsProviderOptions>;
+    discord?: ChannelsIntegrationOptions<DiscordChannelsProviderOptions>;
+    [integrationId: string]: ChannelsIntegrationOptions | undefined;
+}
+export interface ChannelsOptions {
+    /** Platform project whose connections to discover. Falls back to MASTRA_PROJECT_ID. */
+    projectId?: string;
+    /** Optional per-provider overrides keyed by integrationId. */
+    integrations?: ChannelsIntegrationOverrides;
+    client?: ConnectClientOptions;
+    /** How long a resolved snapshot stays fresh, in milliseconds. Default 30_000. `0` revalidates every resolution. */
+    ttlMs?: number;
+}
+/**
+ * The result of resolving a project's connections into a
+ * `ChannelProvider` map. Assignable directly to `Mastra({ channels })`.
+ */
+export type ResolvedChannels = Record<string, ChannelProvider>;
+/**
+ * Callback context passed to `channels()`'s resolver when invoked with a
+ * runtime context. Mirrors the shape used by `tools()` and other dynamic
+ * agent fields — currently unused (per-request provider variance isn't
+ * modeled here) but kept for signature symmetry.
+ */
+export interface ChannelsResolverContext {
+    requestContext?: unknown;
+    mastra?: unknown;
+}
+/**
+ * The value returned by `channels()`. Symmetric with `tools()`:
+ *
+ * - Thenable — `await channels({ projectId })` yields a
+ *   `Record<string, ChannelProvider>` directly, ready to hand to
+ *   `new Mastra({ channels: await channels({ projectId }) })`.
+ * - Callable — `channels(opts)(ctx)` returns the same
+ *   `Record<string, ChannelProvider>`; identical to `await channels(opts)`.
+ * - Handles — `invalidate()` / `refresh()` / `disconnect()` scope to the
+ *   resolver's private cache only. `Mastra({ channels })` reads the
+ *   `Record<string, ChannelProvider>` **synchronously** at construction time,
+ *   so the constructed Mastra instance will not pick up newly-added
+ *   connections or rotated credentials without a restart. These handles are
+ *   for standalone/test usage where the resolver is being called directly —
+ *   not for the Mastra-registered snapshot.
+ */
+export interface ChannelsResolver extends PromiseLike<ResolvedChannels> {
+    /** Callable form used for symmetry with `tools()`; returns the resolved map. */
+    (context?: ChannelsResolverContext): Promise<ResolvedChannels>;
+    /** Drops the cached snapshot; the next resolution fetches fresh from the platform. */
+    invalidate(): void;
+    /** Fetches providers from the platform now and updates the cache. Rejects if the platform fetch fails. */
+    refresh(): Promise<ResolvedChannels>;
+    /** Clears the cached snapshot. Reserved for symmetry with `tools()`; currently a no-op beyond invalidation. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Returns a live channels resolver over the project's Platform connections.
+ * Channel-capable integrations (Slack, Telegram, Discord) with an active
+ * project connection are materialized into `ChannelProvider` instances ready
+ * to hand to `new Mastra({ channels: await channels({...}) })`.
+ *
+ * Configuration errors (missing project id, bad ttlMs, malformed integration
+ * id) throw at call time so they surface at startup. Actionable per-integration
+ * problems during resolution (needs re-auth, ambiguity, missing peer package)
+ * are downgraded to warn-and-skip so one bad integration never takes down the
+ * whole map.
+ *
+ * @example
+ * ```ts
+ * import { Mastra } from '@mastra/core/mastra';
+ * import { channels } from '@mastra/connect';
+ *
+ * export const mastra = new Mastra({
+ *   agents: { pat },
+ *   channels: await channels({ projectId }),
+ * });
+ * ```
+ */
+export declare function channels(options?: ChannelsOptions): ChannelsResolver;
+export {};
+//# sourceMappingURL=channels.d.ts.map

package/dist/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,oBAAoB,EAA2D,MAAM,aAAa,CAAC;AAIjH,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,8BAA8B,EAC/B,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;;;;;;;;;;GAiBG;AACH,KAAK,qBAAqB,CAAC,QAAQ,SAAS,MAAM,IAAI;KAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,KAAK;CAAE,CAAC;AAElF,gFAAgF;AAChF,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,qBAAqB,CAAC,2BAA2B,CAAC,CAAC;AACxH,MAAM,MAAM,+BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnE,qBAAqB,CAAC,8BAA8B,CAAC,CAAC;AACxD,MAAM,MAAM,8BAA8B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,qBAAqB,CAAC,6BAA6B,CAAC,CAAC;AAEzD,wGAAwG;AACxG,MAAM,WAAW,0BAA0B,CAAC,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnF,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0GAA0G;IAC1G,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,0BAA0B,CAAC,4BAA4B,CAAC,CAAC;IACjE,QAAQ,CAAC,EAAE,0BAA0B,CAAC,+BAA+B,CAAC,CAAC;IACvE,OAAO,CAAC,EAAE,0BAA0B,CAAC,8BAA8B,CAAC,CAAC;IACrE,CAAC,aAAa,EAAE,MAAM,GAAG,0BAA0B,GAAG,SAAS,CAAC;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,4BAA4B,CAAC;IAC5C,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,mHAAmH;IACnH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAiB,SAAQ,WAAW,CAAC,gBAAgB,CAAC;IACrE,gFAAgF;IAChF,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/D,sFAAsF;IACtF,UAAU,IAAI,IAAI,CAAC;IACnB,0GAA0G;IAC1G,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACrC,+GAA+G;IAC/G,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,gBAAgB,CAuGxE"}

package/dist/connect.d.ts

@@ -1,66 +1,22 @@
-import type { ConnectClientOptions } from './client.js';
-export interface ConnectIntegrationOptions {
-    /** Pin a specific connection id (bypasses env-var fallback and single-active-connection resolution). */
-    connectionId?: string;
-    /** Restrict the returned toolset to these tool keys. Unknown names throw at build time. */
-    allowTools?: string[];
-    /**
-     * MCP tool keys that may run without tool approval. Every other discovered
-     * MCP tool requires approval, whatever the server's annotations claim, since
-     * a remote catalog cannot be trusted to classify its own tools. An unknown
-     * name skips the provider with a warning, so a typo never widens access.
-     */
-    autoApproveTools?: string[];
-    /** Exclude this provider entirely, even if a connection exists. */
-    disabled?: boolean;
-}
-export interface ConnectOptions {
-    /** Platform project whose connections to discover. Falls back to MASTRA_PROJECT_ID. */
-    projectId?: string;
-    /** Optional per-provider overrides keyed by integrationId. */
-    integrations?: Record<string, ConnectIntegrationOptions>;
-    client?: ConnectClientOptions;
-    /** How long a resolved snapshot stays fresh, in milliseconds. Default 30_000. `0` revalidates every resolution. */
-    ttlMs?: number;
-}
-type ResolvedConnectTools = Record<string, {
-    id: string;
-}>;
+import type { ToolsIntegrationOptions, ToolsOptions, ToolsResolver } from './tools.js';
 /**
- * Live tool resolver returned by `connect()`. Pass it straight to an agent's
- * dynamic `tools` argument: Mastra calls it per generate/stream, so project
- * integrations attached or detached on the platform are reflected without
- * restarting the server. Call it directly (`await tools()`) when you need the
- * current flat tool record.
+ * @deprecated Renamed to {@link ToolsIntegrationOptions}.
  */
-export interface ConnectTools {
-    (ctx?: {
-        requestContext?: unknown;
-        mastra?: unknown;
-    }): Promise<ResolvedConnectTools>;
-    /** Drops the cached snapshot; the next resolution fetches fresh from the platform. */
-    invalidate(): void;
-    /** Fetches tools from the platform now and updates the cache. Rejects if the platform fetch fails. */
-    refresh(): Promise<ResolvedConnectTools>;
-    /** Closes MCP transports owned by this resolver and clears its cached snapshot. */
-    disconnect(): Promise<void>;
-}
+export type ConnectIntegrationOptions = ToolsIntegrationOptions;
 /**
- * Returns a live toolset resolver over the project's Platform connections.
- * HTTP providers are loaded from the shipped `PROVIDERS` registry. MCP providers
- * are discovered from the Platform integration catalog. Tools from every supported
- * provider with a matching project connection are merged into one flat record
- * (matched by `integrationId`). The resolver serves a cached snapshot,
- * revalidating from the platform every `ttlMs`, so integrations attached
- * to (or detached from) the project are picked up (or dropped) without a
- * restart.
+ * @deprecated Renamed to {@link ToolsOptions}.
+ */
+export type ConnectOptions = ToolsOptions;
+/**
+ * @deprecated Renamed to {@link ToolsResolver}.
+ */
+export type ConnectTools = ToolsResolver;
+/**
+ * @deprecated Renamed to {@link tools}.
  *
- * Configuration errors (missing project id, bad ttlMs, malformed integration id)
- * throw here — at call time — so they surface at startup.
- * Expected provider absence is silently skipped. Actionable per-integration
- * problems during resolution (needs re-auth or ambiguity) are downgraded to
- * warn-and-skip so one bad integration never takes down the whole toolset.
+ * `connect(options)` is a drop-in alias for `tools(options)`. Prefer `tools`
+ * from `@mastra/connect` in new code; this export will be removed in the next
+ * minor version.
  */
 export declare function connect(options?: ConnectOptions): ConnectTools;
-export {};
 //# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAA8D,MAAM,aAAa,CAAC;AAOpH,MAAM,WAAW,yBAAyB;IACxC,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,mHAAmH;IACnH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtF,sFAAsF;IACtF,UAAU,IAAI,IAAI,CAAC;IACnB,sGAAsG;IACtG,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzC,mFAAmF;IACnF,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,YAAY,CAkIlE"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,uBAAuB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,YAAY,CAElE"}

package/dist/environment.d.ts

@@ -0,0 +1,48 @@
+import type { SandboxStartHook } from '@mastra/core/workspace';
+import type { ConnectClientOptions } from './client.js';
+export interface EnvironmentIntegrationOptions {
+    /** Pin a specific connection id (bypasses env-var fallback and single-active-connection resolution). */
+    connectionId?: string;
+    /** Exclude this provider entirely, even if a connection exists. */
+    disabled?: boolean;
+}
+export interface EnvironmentOptions {
+    /** Platform project whose connections to discover. Falls back to MASTRA_PROJECT_ID. */
+    projectId?: string;
+    /** Optional per-provider overrides keyed by integrationId. */
+    integrations?: Record<string, EnvironmentIntegrationOptions>;
+    client?: ConnectClientOptions;
+}
+/**
+ * Sandbox credentials materialized from the project's Platform connections.
+ * Pass `env` into the sandbox's environment and `onStart` as (or inside) its
+ * start hook so CLI tooling in the sandbox is authenticated out of the box.
+ */
+export interface ConnectEnvironment {
+    /** Environment variables to inject into the sandbox (e.g. GH_TOKEN). Never log these. */
+    env: Record<string, string | undefined>;
+    /** Runs provider setup inside the sandbox (e.g. git credential wiring). Safe no-op when nothing to do. */
+    onStart: SandboxStartHook;
+}
+/**
+ * Resolves the project's Platform connections into sandbox credentials:
+ * environment variables plus a start hook that finishes in-sandbox setup.
+ * Currently GitHub-aware (`GH_TOKEN`/`GITHUB_TOKEN` + git credential helper);
+ * more providers plug in over time.
+ *
+ * Connection resolution matches `connect()`: a per-integration `connectionId`
+ * or the provider's `MASTRA_*_CONNECTION_ID` env var wins, else a single
+ * active connection; ambiguity, needs_reauth, and credential-fetch failures
+ * warn and skip that provider. Configuration errors (missing project id,
+ * malformed integration id) throw here so they surface at startup.
+ *
+ * The returned `env` is a snapshot: call `environment()` again for a fresh
+ * token when starting new sandboxes.
+ *
+ * @example
+ * const { env, onStart } = await environment({ projectId });
+ * const sandbox = new E2BSandbox({ env, onStart });
+ * // in the sandbox: `gh pr list`, `git clone https://github.com/org/repo` just work
+ */
+export declare function environment(options?: EnvironmentOptions): Promise<ConnectEnvironment>;
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EAAE,oBAAoB,EAAwB,MAAM,aAAa,CAAC;AAK9E,MAAM,WAAW,6BAA6B;IAC5C,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IAC7D,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,0GAA0G;IAC1G,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAuDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuD/F"}