@mastra/connect 0.3.1-alpha.0 → 0.4.0-alpha.0

package/dist/index.d.ts

@@ -1,11 +1,18 @@
+export { tools } from './tools.js';
+export type { ToolsOptions, ToolsIntegrationOptions, ToolsResolver } from './tools.js';
 export { connect } from './connect.js';
 export type { ConnectOptions, ConnectIntegrationOptions, ConnectTools } from './connect.js';
+export { channels } from './channels.js';
+export type { ChannelsOptions, ChannelsIntegrationOptions, ChannelsResolver, ChannelsResolverContext, ResolvedChannels, } from './channels.js';
+export type { ChannelProviderRegistration, ChannelBuildContext } from './providers/channel-provider.js';
 export { credential } from './credential.js';
+export { environment } from './environment.js';
+export type { ConnectEnvironment, EnvironmentIntegrationOptions, EnvironmentOptions } from './environment.js';
 export { MastraConnectError } from './errors.js';
 export type { MastraConnectErrorCode } from './errors.js';
 export type { ConnectClientOptions, ConnectionCredential, ProjectConnection } from './client.js';
 export type { ProviderToolsOptions, ProxyToolConfig, ProxyToolContext } from './toolset.js';
 export { defineProxyTool, resolveConnectionId, applyAllowTools } from './toolset.js';
-export { PROVIDERS, findRegistration } from './registry.js';
+export { TOOLS, PROVIDERS, CHANNELS, findRegistration, findChannelRegistration } from './registry.js';
 export type { McpProviderRegistration, ProviderRegistration, ProxyProviderRegistration } from './registry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,yBAAyB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,yBAAyB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACxG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9G,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACtG,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -342,6 +342,106 @@ async function proxyRequestWithResponse(client, connectionId, options) {
 	}
 }
 //#endregion
+//#region src/providers/channels.ts
+function credentialToken$1(credential) {
+	return credential.type === "oauth2" ? credential.accessToken : credential.apiKey;
+}
+function missingPeerError(integrationId, packageName, error) {
+	return new MastraConnectError("invalid_options", `channels() cannot build '${integrationId}' provider: install '${packageName}' as a dependency of your app (${error instanceof Error ? error.message : String(error)}).`);
+}
+const RESERVED_OPTION_KEYS = {
+	slack: [
+		"baseUrl",
+		"refreshToken",
+		"token",
+		"encryptionKey"
+	],
+	telegram: [
+		"baseUrl",
+		"apiBaseUrl",
+		"botToken",
+		"encryptionKey"
+	],
+	discord: ["baseUrl", "encryptionKey"]
+};
+function stripReservedOptions(integrationId, options) {
+	if (!options) return options;
+	const reserved = RESERVED_OPTION_KEYS[integrationId];
+	if (!reserved) return options;
+	const stripped = [];
+	const filtered = {};
+	for (const [key, value] of Object.entries(options)) {
+		if (reserved.includes(key)) {
+			stripped.push(key);
+			continue;
+		}
+		filtered[key] = value;
+	}
+	if (stripped.length > 0) console.warn(`[@mastra/connect] ${integrationId} channel: ignoring reserved providerOptions field(s): ${stripped.map((k) => `'${k}'`).join(", ")}. These are managed by the connection credential or the Mastra server config.`);
+	return filtered;
+}
+const CHANNELS$1 = [
+	{
+		integrationId: "slack",
+		async build(credential, options) {
+			const refreshToken = credentialToken$1(credential);
+			let mod;
+			try {
+				mod = await import("@mastra/slack");
+			} catch (error) {
+				throw missingPeerError("slack", "@mastra/slack", error);
+			}
+			const safeOptions = stripReservedOptions("slack", options);
+			return new mod.SlackProvider({
+				refreshToken,
+				...safeOptions ?? {}
+			});
+		}
+	},
+	{
+		integrationId: "telegram",
+		async build(credential, options) {
+			const botToken = credentialToken$1(credential);
+			let mod;
+			try {
+				mod = await import("@mastra/telegram");
+			} catch (error) {
+				throw missingPeerError("telegram", "@mastra/telegram", error);
+			}
+			const safeOptions = stripReservedOptions("telegram", options);
+			return new mod.TelegramProvider({
+				botToken,
+				...safeOptions ?? {}
+			});
+		}
+	},
+	{
+		integrationId: "discord",
+		async build(credential, options, context) {
+			const botToken = credentialToken$1(credential);
+			const metadata = context?.context?.metadata ?? {};
+			const applicationId = options?.applicationId ?? (typeof metadata.applicationId === "string" ? metadata.applicationId : void 0) ?? (typeof metadata.application_id === "string" ? metadata.application_id : void 0);
+			const publicKey = options?.publicKey ?? (typeof metadata.publicKey === "string" ? metadata.publicKey : void 0) ?? (typeof metadata.public_key === "string" ? metadata.public_key : void 0);
+			let mod;
+			try {
+				mod = await import("@mastra/discord");
+			} catch (error) {
+				throw missingPeerError("discord", "@mastra/discord", error);
+			}
+			if (!applicationId || !publicKey) console.warn(`[@mastra/connect] discord channel: missing ${[!applicationId && "applicationId", !publicKey && "publicKey"].filter(Boolean).join(" + ")} on the connection. Store them on the connection's metadata or pass them via integrations.discord.providerOptions.`);
+			const { applicationId: _optAppId, publicKey: _optPubKey, ...rest } = options ?? {};
+			return new mod.DiscordProvider({
+				app: {
+					botToken,
+					applicationId,
+					publicKey
+				},
+				...rest
+			});
+		}
+	}
+];
+//#endregion
 //#region src/runtime/platform-proxy.ts
 /** Maps the platform credential to the field names templates are written against. */
 function toTemplateCredentials(credential) {
@@ -65717,7 +65817,7 @@ function createWorkosTools(options) {
 * Providers with checked-in HTTP toolsets. MCP-backed providers are discovered
 * from the Platform integration catalog at runtime.
 */
-const PROVIDERS = [
+const TOOLS = [
 	anthropicProvider,
 	clerkProvider,
 	discordProvider,
@@ -65744,18 +65844,84 @@ const PROVIDERS = [
 		createTools: createWorkosTools
 	}
 ];
+/**
+* @deprecated Use `TOOLS`. This alias is retained for one release cycle so
+* downstream consumers keep working; it will be removed in the next minor.
+*/
+const PROVIDERS = TOOLS;
 function findRegistration(integrationId) {
-	return PROVIDERS.find((p) => p.integrationId === integrationId);
+	return TOOLS.find((p) => p.integrationId === integrationId);
+}
+/**
+* Channel-capable providers with a hand-maintained `channels()` registration.
+* The launch ships three (Slack, Telegram, Discord); the provider generator
+* grows to cover new entries when a fourth lands.
+*/
+const CHANNELS = CHANNELS$1;
+function findChannelRegistration(integrationId) {
+	return CHANNELS.find((c) => c.integrationId === integrationId);
 }
 //#endregion
-//#region src/connect.ts
-const DEFAULT_TTL_MS = 3e4;
+//#region src/resolution.ts
+const INTEGRATION_ID_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;
+function validateIntegrationOverrides(integrations) {
+	for (const integrationId of Object.keys(integrations ?? {})) if (!INTEGRATION_ID_PATTERN.test(integrationId)) throw new MastraConnectError("invalid_options", `Invalid provider '${integrationId}' in integrations option: expected 1-128 letters, numbers, underscores, or hyphens.`);
+}
+function connectionIdEnvVar(integrationId) {
+	return `MASTRA_${integrationId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_CONNECTION_ID`;
+}
+function groupByIntegrationId(connections) {
+	const byIntegrationId = /* @__PURE__ */ new Map();
+	for (const connection of connections) {
+		const list = byIntegrationId.get(connection.integrationId) ?? [];
+		list.push(connection);
+		byIntegrationId.set(connection.integrationId, list);
+	}
+	return byIntegrationId;
+}
+/**
+* Resolves the connection to use for one provider, per the contract:
+* option/env var wins; else a single active connection; anything else
+* (ambiguity, needs_reauth, no usable candidate) warns and skips so one bad
+* integration never takes down the whole resolution. A needs_reauth
+* connection is never silently mapped.
+*/
+function resolveConnection(request, candidates) {
+	const integrationId = request.integrationId;
+	const directed = request.connectionId?.trim() || process.env[request.envVar]?.trim() || void 0;
+	if (directed) {
+		const match = candidates.find((connection) => connection.id === directed);
+		if (!match) {
+			console.warn(`[@mastra/connect] Skipping ${integrationId}: pinned connection ${directed} is not attached to this project.`);
+			return;
+		}
+		if (match.status === "needs_reauth") {
+			console.warn(`[@mastra/connect] Skipping ${integrationId}: connection ${directed} needs re-auth.`);
+			return;
+		}
+		if (match.status !== "active") {
+			console.warn(`[@mastra/connect] Skipping ${integrationId}: connection ${directed} is not active (status '${match.status}').`);
+			return;
+		}
+		return directed;
+	}
+	const active = candidates.filter((connection) => connection.status === "active");
+	if (active.length === 1) return active[0].id;
+	if (active.length === 0) {
+		console.warn(`[@mastra/connect] Skipping ${integrationId}: no active connections (found ${candidates.length} in other states).`);
+		return;
+	}
+	console.warn(`[@mastra/connect] Skipping ${integrationId}: ${active.length} active connections; pin one with connectionId or ${request.envVar}.`);
+}
+//#endregion
+//#region src/tools.ts
+const DEFAULT_TTL_MS$1 = 3e4;
 /** Minimum wait after a failed platform fetch before another background revalidation. */
-const FAILURE_COOLDOWN_MS = 3e4;
+const FAILURE_COOLDOWN_MS$1 = 3e4;
 let nextResolverId = 0;
 /**
 * Returns a live toolset resolver over the project's Platform connections.
-* HTTP providers are loaded from the shipped `PROVIDERS` registry. MCP providers
+* HTTP providers are loaded from the shipped `TOOLS` 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,
@@ -65769,11 +65935,11 @@ let nextResolverId = 0;
 * problems during resolution (needs re-auth or ambiguity) are downgraded to
 * warn-and-skip so one bad integration never takes down the whole toolset.
 */
-function connect(options = {}) {
+function tools(options = {}) {
 	const projectId = options.projectId?.trim() || process.env.MASTRA_PROJECT_ID?.trim();
 	if (!projectId) throw new MastraConnectError("missing_project_id", "Missing project id: set MASTRA_PROJECT_ID or pass projectId.");
 	if (options.ttlMs !== void 0 && (!Number.isFinite(options.ttlMs) || options.ttlMs < 0)) throw new MastraConnectError("invalid_options", `Invalid ttlMs (${options.ttlMs}): expected a finite number of milliseconds >= 0.`);
-	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS$1;
 	const client = resolveClient(options.client);
 	const resolverId = ++nextResolverId;
 	const mcpClients = /* @__PURE__ */ new Map();
@@ -65795,7 +65961,7 @@ function connect(options = {}) {
 			connections,
 			catalog: catalogResult.value
 		};
-		const checkedIn = new Set(PROVIDERS.map((registration) => registration.integrationId));
+		const checkedIn = new Set(TOOLS.map((registration) => registration.integrationId));
 		if (connections.some((connection) => connection.status === "active" && !checkedIn.has(connection.integrationId) && !options.integrations?.[connection.integrationId]?.disabled)) throw catalogResult.reason;
 		const reason = catalogResult.reason;
 		console.warn(`[@mastra/connect] Platform catalog unavailable (${reason instanceof Error ? reason.message : String(reason)}); resolving checked-in providers only.`);
@@ -65833,7 +65999,7 @@ function connect(options = {}) {
 		if (cache && Date.now() - cache.fetchedAt < ttlMs) return cache.snapshot;
 		if (cache) {
 			const staleSnapshot = cache.snapshot;
-			if (!(lastFailureAt !== void 0 && Date.now() - lastFailureAt < FAILURE_COOLDOWN_MS) && !inflight && !closing) {
+			if (!(lastFailureAt !== void 0 && Date.now() - lastFailureAt < FAILURE_COOLDOWN_MS$1) && !inflight && !closing) {
 				const staleFetchedAt = cache.fetchedAt;
 				refresh().catch((error) => {
 					console.warn(`[@mastra/connect] Keeping cached tools (fetched ${Date.now() - staleFetchedAt}ms ago); platform refresh failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -65864,16 +66030,9 @@ function connect(options = {}) {
 		}
 	});
 }
-function validateIntegrationOverrides(integrations) {
-	const integrationIdPattern = /^[a-zA-Z0-9_-]{1,128}$/;
-	for (const integrationId of Object.keys(integrations ?? {})) if (!integrationIdPattern.test(integrationId)) throw new MastraConnectError("invalid_options", `Invalid provider '${integrationId}' in integrations option: expected 1-128 letters, numbers, underscores, or hyphens.`);
-}
-function connectionIdEnvVar(integrationId) {
-	return `MASTRA_${integrationId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_CONNECTION_ID`;
-}
 function buildRequests(integrations, catalog) {
 	const overrides = integrations ?? {};
-	const registrations = new Map(PROVIDERS.map((registration) => [registration.integrationId, registration]));
+	const registrations = new Map(TOOLS.map((registration) => [registration.integrationId, registration]));
 	const catalogIds = new Set(catalog.map((integration) => integration.id));
 	for (const integration of catalog) {
 		if (!integration.capabilities.mcp) continue;
@@ -65907,7 +66066,11 @@ async function mapTools(connections, requests, options, client, mcpClients, reso
 		try {
 			const candidates = byIntegrationId.get(integrationId) ?? [];
 			if (candidates.length === 0) continue;
-			const connectionId = resolveProviderConnection(request, candidates);
+			const connectionId = resolveConnection({
+				integrationId,
+				envVar: request.registration.envVar,
+				connectionId: request.options.connectionId
+			}, candidates);
 			if (!connectionId) continue;
 			if (request.registration.transport === "mcp") {
 				activeMcpIntegrations.add(integrationId);
@@ -65967,51 +66130,192 @@ async function discoverMcpTools(input) {
 	if (unknown.length > 0) throw new MastraConnectError("invalid_options", `Unknown tool name(s) in autoApproveTools for '${registration.integrationId}': ${unknown.join(", ")}. Known tools: ${Object.keys(discovery.tools).join(", ")}.`);
 	return applyAllowTools(discovery.tools, allowTools);
 }
-function groupByIntegrationId(connections) {
-	const byIntegrationId = /* @__PURE__ */ new Map();
-	for (const connection of connections) {
-		const list = byIntegrationId.get(connection.integrationId) ?? [];
-		list.push(connection);
-		byIntegrationId.set(connection.integrationId, list);
-	}
-	return byIntegrationId;
+//#endregion
+//#region src/connect.ts
+/**
+* @deprecated Use `tools` from `@mastra/connect` instead. This module is a
+* thin re-export retained for one release cycle so downstream consumers keep
+* working; it will be removed in the next minor.
+*/
+/**
+* @deprecated Renamed to {@link tools}.
+*
+* `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.
+*/
+function connect(options = {}) {
+	return tools(options);
 }
-function readEnvConnectionId(registration) {
-	return process.env[registration.envVar]?.trim() || void 0;
+//#endregion
+//#region src/channels.ts
+const DEFAULT_TTL_MS = 3e4;
+/** Minimum wait after a failed platform fetch before another background revalidation. */
+const FAILURE_COOLDOWN_MS = 3e4;
+/**
+* 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 }),
+* });
+* ```
+*/
+function channels(options = {}) {
+	const projectId = options.projectId?.trim() || process.env.MASTRA_PROJECT_ID?.trim();
+	if (!projectId) throw new MastraConnectError("missing_project_id", "Missing project id: set MASTRA_PROJECT_ID or pass projectId.");
+	if (options.ttlMs !== void 0 && (!Number.isFinite(options.ttlMs) || options.ttlMs < 0)) throw new MastraConnectError("invalid_options", `Invalid ttlMs (${options.ttlMs}): expected a finite number of milliseconds >= 0.`);
+	validateIntegrationOverrides(options.integrations);
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	const client = resolveClient(options.client);
+	let cache;
+	let inflight;
+	let lastFailureAt;
+	const buildSnapshot = async () => {
+		let connections;
+		try {
+			connections = await listProjectConnections(client, projectId);
+		} catch (error) {
+			lastFailureAt = Date.now();
+			throw error;
+		}
+		const byIntegrationId = groupByIntegrationId(connections);
+		const providers = {};
+		for (const registration of CHANNELS) {
+			const integrationId = registration.integrationId;
+			const overrides = options.integrations?.[integrationId] ?? {};
+			if (overrides.disabled) continue;
+			const candidates = byIntegrationId.get(integrationId) ?? [];
+			if (candidates.length === 0) continue;
+			const connectionId = selectChannelConnection(integrationId, overrides.connectionId, candidates);
+			if (!connectionId) continue;
+			const provider = await buildProvider(registration, connectionId, overrides, client);
+			if (!provider) continue;
+			providers[integrationId] = provider;
+		}
+		lastFailureAt = void 0;
+		return providers;
+	};
+	const refresh = () => {
+		if (!inflight) inflight = (async () => {
+			try {
+				const providers = await buildSnapshot();
+				cache = {
+					providers,
+					fetchedAt: Date.now()
+				};
+				return providers;
+			} finally {
+				inflight = void 0;
+			}
+		})();
+		return inflight;
+	};
+	const resolve = async () => {
+		if (cache && Date.now() - cache.fetchedAt < ttlMs) return cache.providers;
+		if (cache) {
+			const stale = cache.providers;
+			if (!(lastFailureAt !== void 0 && Date.now() - lastFailureAt < FAILURE_COOLDOWN_MS) && !inflight) {
+				const staleFetchedAt = cache.fetchedAt;
+				refresh().catch((error) => {
+					console.warn(`[@mastra/connect] Keeping cached channels (fetched ${Date.now() - staleFetchedAt}ms ago); platform refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+				});
+			}
+			return stale;
+		}
+		return refresh();
+	};
+	const invocable = ((_context) => resolve());
+	invocable.invalidate = () => {
+		cache = void 0;
+	};
+	invocable.refresh = refresh;
+	invocable.disconnect = async () => {
+		cache = void 0;
+	};
+	invocable.then = ((onfulfilled, onrejected) => resolve().then(onfulfilled, onrejected));
+	return invocable;
+}
+async function buildProvider(registration, connectionId, overrides, client) {
+	let credential;
+	try {
+		credential = await getCredential(client, connectionId);
+	} catch (error) {
+		console.warn(`[@mastra/connect] Skipping ${registration.integrationId} channel: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+	let context = {
+		connectionId,
+		client
+	};
+	try {
+		context = {
+			connectionId,
+			client,
+			context: await getConnectionContext(client, connectionId)
+		};
+	} catch {}
+	try {
+		return await registration.build(credential, overrides.providerOptions ?? {}, context);
+	} catch (error) {
+		console.warn(`[@mastra/connect] Skipping ${registration.integrationId} channel: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
 }
 /**
-* Resolves the connection to use for one provider, per the contract:
-* option/env var wins; else a single active connection; anything else
-* (ambiguity, needs_reauth, no usable candidate) warns and skips so one bad
-* integration never takes down the whole toolset resolution. A needs_reauth
-* connection is never silently mapped.
+* Selects the connection `channels()` should use for one provider.
+*
+* - Pinned `connectionId` (from `integrations.<id>.connectionId`) wins, but is
+*   skipped if the pinned id isn't attached to the project or the connection
+*   isn't `active`.
+* - Otherwise, the single active connection is used.
+* - When more than one active connection exists, this warns naming the chosen
+*   id and picks the first active connection. There is no env-var fallback;
+*   pin explicitly with `integrations.<id>.connectionId` when the deterministic
+*   choice matters.
 */
-function resolveProviderConnection(request, candidates) {
-	const integrationId = request.registration.integrationId;
-	const directed = request.options.connectionId?.trim() || readEnvConnectionId(request.registration);
+function selectChannelConnection(integrationId, pinnedId, candidates) {
+	const directed = pinnedId?.trim() || void 0;
 	if (directed) {
 		const match = candidates.find((connection) => connection.id === directed);
 		if (!match) {
-			console.warn(`[@mastra/connect] Skipping ${integrationId}: pinned connection ${directed} is not attached to this project.`);
+			console.warn(`[@mastra/connect] Skipping ${integrationId} channel: pinned connection ${directed} is not attached to this project.`);
 			return;
 		}
 		if (match.status === "needs_reauth") {
-			console.warn(`[@mastra/connect] Skipping ${integrationId}: connection ${directed} needs re-auth.`);
+			console.warn(`[@mastra/connect] Skipping ${integrationId} channel: connection ${directed} needs re-auth.`);
 			return;
 		}
 		if (match.status !== "active") {
-			console.warn(`[@mastra/connect] Skipping ${integrationId}: connection ${directed} is not active (status '${match.status}').`);
+			console.warn(`[@mastra/connect] Skipping ${integrationId} channel: connection ${directed} is not active (status '${match.status}').`);
 			return;
 		}
 		return directed;
 	}
 	const active = candidates.filter((connection) => connection.status === "active");
-	if (active.length === 1) return active[0].id;
 	if (active.length === 0) {
-		console.warn(`[@mastra/connect] Skipping ${integrationId}: no active connections (found ${candidates.length} in other states).`);
+		console.warn(`[@mastra/connect] Skipping ${integrationId} channel: no active connections (found ${candidates.length} in other states).`);
 		return;
 	}
-	console.warn(`[@mastra/connect] Skipping ${integrationId}: ${active.length} active connections; pin one with connectionId or ${request.registration.envVar}.`);
+	if (active.length === 1) return active[0].id;
+	const chosen = active[0].id;
+	const others = active.slice(1).map((connection) => connection.id).join(", ");
+	console.warn(`[@mastra/connect] ${integrationId} channel: found ${active.length} active connections; using ${chosen}. Ignoring ${others}. Pin one with integrations.${integrationId}.connectionId to silence this warning.`);
+	return chosen;
 }
 //#endregion
 //#region src/credential.ts
@@ -66023,6 +66327,108 @@ async function credential(connectionId, options) {
 	return getCredential(resolveClient(options?.client), connectionId);
 }
 //#endregion
-export { MastraConnectError, PROVIDERS, applyAllowTools, connect, credential, defineProxyTool, findRegistration, resolveConnectionId };
+//#region src/environment.ts
+function credentialToken(credential) {
+	return credential.type === "oauth2" ? credential.accessToken : credential.apiKey;
+}
+/**
+* Wires git's credential helper to read the token from the environment at use
+* time, so the secret lives in the process env rather than in git config or
+* remote URLs. `gh` needs no setup: it honors GH_TOKEN directly.
+*/
+const GITHUB_GIT_CREDENTIAL_HELPER = "!f() { echo username=x-access-token; echo \"password=$GH_TOKEN\"; }; f";
+/** Providers that know how to materialize sandbox credentials. */
+const ENVIRONMENT_CONTRIBUTORS = [{
+	integrationId: "github",
+	envVar: "MASTRA_GITHUB_CONNECTION_ID",
+	build(credential) {
+		const token = credentialToken(credential);
+		return {
+			env: {
+				GH_TOKEN: token,
+				GITHUB_TOKEN: token
+			},
+			onStart: async ({ sandbox }) => {
+				if (!sandbox.executeCommand) {
+					console.warn("[@mastra/connect] github environment: sandbox does not support executeCommand; skipping git credential setup (gh still works via GH_TOKEN).");
+					return;
+				}
+				await sandbox.executeCommand("git", [
+					"config",
+					"--global",
+					"credential.https://github.com.helper",
+					GITHUB_GIT_CREDENTIAL_HELPER
+				]);
+			}
+		};
+	}
+}];
+/**
+* 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
+*/
+async function environment(options = {}) {
+	const projectId = options.projectId?.trim() || process.env.MASTRA_PROJECT_ID?.trim();
+	if (!projectId) throw new MastraConnectError("missing_project_id", "Missing project id: set MASTRA_PROJECT_ID or pass projectId.");
+	validateIntegrationOverrides(options.integrations);
+	const client = resolveClient(options.client);
+	const byIntegrationId = groupByIntegrationId(await listProjectConnections(client, projectId));
+	const env = {};
+	const hooks = [];
+	for (const contributor of ENVIRONMENT_CONTRIBUTORS) {
+		const integrationId = contributor.integrationId;
+		const overrides = options.integrations?.[integrationId] ?? {};
+		if (overrides.disabled) continue;
+		const candidates = byIntegrationId.get(integrationId) ?? [];
+		if (candidates.length === 0) continue;
+		const connectionId = resolveConnection({
+			integrationId,
+			envVar: contributor.envVar,
+			connectionId: overrides.connectionId
+		}, candidates);
+		if (!connectionId) continue;
+		let credential;
+		try {
+			credential = await getCredential(client, connectionId);
+		} catch (error) {
+			console.warn(`[@mastra/connect] Skipping ${integrationId} environment: ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		const contribution = contributor.build(credential);
+		for (const [key, value] of Object.entries(contribution.env)) {
+			if (key in env) console.warn(`[@mastra/connect] ${integrationId} environment overwrites env var '${key}' set by an earlier provider.`);
+			env[key] = value;
+		}
+		if (contribution.onStart) hooks.push({
+			integrationId,
+			hook: contribution.onStart
+		});
+	}
+	const onStart = async (args) => {
+		for (const { hook } of hooks) await hook(args);
+	};
+	return {
+		env,
+		onStart
+	};
+}
+//#endregion
+export { CHANNELS, MastraConnectError, PROVIDERS, TOOLS, applyAllowTools, channels, connect, credential, defineProxyTool, environment, findChannelRegistration, findRegistration, resolveConnectionId, tools };
 
 //# sourceMappingURL=index.js.map