@mastra/connect 1.0.0-alpha.2 → 1.0.0

package/dist/index.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _mastra_mcp = require("@mastra/mcp");
 let zod = require("zod");
+let _mastra_core_observability = require("@mastra/core/observability");
 let _mastra_core_tools = require("@mastra/core/tools");
 //#region src/errors.ts
 const MAX_DETAIL_LENGTH = 2e3;
@@ -105,6 +106,98 @@ async function extractProblemDetail(response) {
 	return { isProblemJson };
 }
 //#endregion
+//#region src/instrumentation.ts
+const ID_SEGMENT_ROUTES = [{
+	prefix: "/v2/connections/",
+	placeholder: "{connectionId}",
+	key: "connectionId"
+}, {
+	prefix: "/v2/projects/",
+	placeholder: "{projectId}",
+	key: "projectId"
+}];
+const PROXY_SEGMENT = "/proxy/";
+/** Describes a platform request for span naming without leaking query params, ids, or vendor path segments. */
+function describePlatformCall(method, rawPath) {
+	const path = rawPath.split("?")[0];
+	let route = path;
+	const descriptor = {
+		method,
+		route,
+		isProxy: false
+	};
+	for (const idRoute of ID_SEGMENT_ROUTES) {
+		if (!path.startsWith(idRoute.prefix)) continue;
+		const rest = path.slice(idRoute.prefix.length);
+		const slash = rest.indexOf("/");
+		const id = slash === -1 ? rest : rest.slice(0, slash);
+		const tail = slash === -1 ? "" : rest.slice(slash);
+		descriptor[idRoute.key] = safeDecode(id);
+		route = `${idRoute.prefix}${idRoute.placeholder}${tail}`;
+		break;
+	}
+	const proxyIndex = route.indexOf(PROXY_SEGMENT);
+	if (proxyIndex !== -1) {
+		descriptor.isProxy = true;
+		route = `${route.slice(0, proxyIndex + 7)}*`;
+	}
+	descriptor.route = route;
+	return descriptor;
+}
+function safeDecode(segment) {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return segment;
+	}
+}
+/**
+* Starts a GENERIC child span for an outbound connect HTTP call, or returns
+* `undefined` when no ambient span is active. Span creation failures are
+* swallowed: instrumentation must never break a request.
+*/
+function startPlatformCallSpan(descriptor) {
+	let parent;
+	try {
+		parent = (0, _mastra_core_observability.resolveCurrentSpan)();
+		if (!parent) return void 0;
+		return parent.createChildSpan({
+			type: _mastra_core_observability.SpanType.GENERIC,
+			name: `connect.${descriptor.isProxy ? "proxy" : "platform"} ${descriptor.method} ${descriptor.route}`,
+			metadata: {
+				method: descriptor.method,
+				route: descriptor.route,
+				...descriptor.connectionId ? { connectionId: descriptor.connectionId } : {},
+				...descriptor.projectId ? { projectId: descriptor.projectId } : {}
+			}
+		});
+	} catch {
+		return;
+	}
+}
+/** Ends a platform-call span with the response status. Never throws. */
+function endPlatformCallSpan(span, status) {
+	if (!span) return;
+	try {
+		span.end({ metadata: { status } });
+	} catch {}
+}
+/**
+* Records a transport-level failure on a platform-call span. Nothing from the
+* original error is recorded — fetch failures can embed the request URL in
+* both `message` and `name`, which may carry secret query params — so the
+* span gets a fixed, constant error. Never throws.
+*/
+function errorPlatformCallSpan(span, _error) {
+	if (!span) return;
+	try {
+		span.error({
+			error: /* @__PURE__ */ new Error("connect request failed"),
+			endSpan: true
+		});
+	} catch {}
+}
+//#endregion
 //#region src/client.ts
 const DEFAULT_INTEGRATIONS_URL = "https://integrations.mastra.ai";
 const REGIONAL_INTEGRATIONS_URLS = {
@@ -147,20 +240,25 @@ function redact(message, accessToken) {
 	return message.split(accessToken).join("[REDACTED]");
 }
 async function platformFetch(client, path, init) {
+	const span = startPlatformCallSpan(describePlatformCall(init?.method ?? "GET", path));
 	try {
-		return await client.fetch(`${client.baseUrl}${path}`, {
+		const response = await client.fetch(`${client.baseUrl}${path}`, {
 			...init,
 			headers: {
 				...client.headers,
 				...init?.headers
 			}
 		});
+		endPlatformCallSpan(span, response.status);
+		return response;
 	} catch (error) {
 		if (error instanceof Error && error.message.includes(client.accessToken)) {
 			const redacted = new Error(redact(error.message, client.accessToken));
 			redacted.name = error.name;
+			errorPlatformCallSpan(span, redacted);
 			throw redacted;
 		}
+		errorPlatformCallSpan(span, error);
 		throw error;
 	}
 }
@@ -339,9 +437,6 @@ function assertValidBaseUrlOverride(baseUrlOverride) {
 	if (parsed.protocol !== "https:") throw new MastraConnectError("invalid_options", `Invalid baseUrlOverride '${baseUrlOverride}': only https:// URLs are allowed.`);
 	if (parsed.username || parsed.password) throw new MastraConnectError("invalid_options", `Invalid baseUrlOverride '${baseUrlOverride}': embedded credentials are not allowed.`);
 }
-async function proxyRequest(client, connectionId, options) {
-	return (await proxyRequestWithResponse(client, connectionId, options)).data;
-}
 /** Preserves HTTP metadata for tools with status-dependent provider contracts. */
 async function proxyRequestWithResponse(client, connectionId, options) {
 	const cleanPath = options.path.replace(/^\/+/, "");
@@ -428,37 +523,64 @@ async function proxyRequestWithResponse(client, connectionId, options) {
 }
 //#endregion
 //#region src/toolset.ts
-/** Resolves a connection id lazily at execute time: option → env var → typed error naming the env var. */
-function resolveConnectionId(envVar, connectionId) {
-	const resolved = connectionId?.trim() || process.env[envVar]?.trim();
-	if (!resolved) throw new MastraConnectError("missing_connection_id", `Missing connection id: set ${envVar} or pass connectionId.`);
-	return resolved;
+/**
+* Compiles a tool-filter entry containing `*` wildcards into an anchored
+* regex; every other character matches literally.
+*/
+function compileToolPattern(pattern) {
+	const escaped = pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${escaped}$`);
 }
 /**
-* Wraps `createTool` so the tool executes through the platform connection
-* proxy. Connection id and client config resolve lazily inside execute, so
-* building tools without env vars set never throws.
+* Returns a predicate testing tool keys against filter `entries`, where an
+* entry containing `*` is a glob and anything else matches literally. Used
+* where keys are only known later (MCP approval predicates); list-shaped
+* call sites expand eagerly with {@link expandToolPatterns} instead.
 */
-function defineProxyTool(context, config) {
-	return (0, _mastra_core_tools.createTool)({
-		id: config.id,
-		description: config.description,
-		inputSchema: config.inputSchema,
-		outputSchema: config.outputSchema,
-		execute: async (input) => {
-			const connectionId = resolveConnectionId(context.envVar, context.options?.connectionId);
-			const raw = await proxyRequest(resolveClient(context.options?.client), connectionId, config.request(input));
-			return config.transform(raw, input);
+function compileToolMatcher(entries) {
+	const literals = /* @__PURE__ */ new Set();
+	const patterns = [];
+	for (const entry of entries) if (entry.includes("*")) patterns.push(compileToolPattern(entry));
+	else literals.add(entry);
+	return (toolKey) => literals.has(toolKey) || patterns.some((pattern) => pattern.test(toolKey));
+}
+/**
+* Expands `*` glob entries against the known tool keys, preserving order and
+* de-duplicating. Literal entries pass through untouched (callers validate
+* those against their own key sets). A glob that matches nothing throws:
+* like an unknown literal name, a dead pattern in access-limiting config is
+* a typo that must surface instead of silently filtering nothing.
+*/
+function expandToolPatterns(entries, knownKeys, label) {
+	const expanded = [];
+	const seen = /* @__PURE__ */ new Set();
+	const push = (key) => {
+		if (seen.has(key)) return;
+		seen.add(key);
+		expanded.push(key);
+	};
+	for (const entry of entries) {
+		if (!entry.includes("*")) {
+			push(entry);
+			continue;
 		}
-	});
+		const pattern = compileToolPattern(entry);
+		const matches = knownKeys.filter((key) => pattern.test(key));
+		if (matches.length === 0) throw new MastraConnectConfigError(`Pattern '${entry}' in ${label} matched no tools. Known tools: ${knownKeys.join(", ")}.`);
+		for (const match of matches) push(match);
+	}
+	return expanded;
 }
 /**
-* Filters a toolset by tool key. Throws at build time on unknown names so
-* typos in access-limiting config surface immediately.
+* Filters a toolset by tool key. Entries containing `*` are globs expanded
+* against the toolset's keys. Throws at build time on unknown names and on
+* globs that match nothing, so typos in access-limiting config surface
+* immediately.
 */
-function applyAllowTools(tools, allowTools) {
-	if (!allowTools) return tools;
+function applyAllowTools(tools, allowToolsInput) {
+	if (!allowToolsInput) return tools;
 	const known = Object.keys(tools);
+	const allowTools = expandToolPatterns(allowToolsInput, known, "allowTools");
 	const unknown = allowTools.filter((name) => !known.includes(name));
 	if (unknown.length > 0) throw new Error(`Unknown tool name(s) in allowTools: ${unknown.join(", ")}. Known tools: ${known.join(", ")}.`);
 	const filtered = {};
@@ -466,13 +588,15 @@ function applyAllowTools(tools, allowTools) {
 	return filtered;
 }
 /**
-* Removes tool keys from a toolset. Throws at build time on unknown names so
-* typos in access-limiting config surface immediately instead of silently
-* removing nothing.
+* Removes tool keys from a toolset. Entries containing `*` are globs
+* expanded against the toolset's keys. Throws at build time on unknown names
+* and on globs that match nothing, so typos in access-limiting config
+* surface immediately instead of silently removing nothing.
 */
-function applyDisallowTools(tools, disallowTools) {
-	if (!disallowTools || disallowTools.length === 0) return tools;
+function applyDisallowTools(tools, disallowToolsInput) {
+	if (!disallowToolsInput || disallowToolsInput.length === 0) return tools;
 	const known = Object.keys(tools);
+	const disallowTools = expandToolPatterns(disallowToolsInput, known, "disallowTools");
 	const unknown = disallowTools.filter((name) => !known.includes(name));
 	if (unknown.length > 0) throw new Error(`Unknown tool name(s) in disallowTools: ${unknown.join(", ")}. Known tools: ${known.join(", ")}.`);
 	const remove = new Set(disallowTools);
@@ -710,7 +834,7 @@ function buildProxyMultiConnectionTools(input) {
 */
 async function buildMcpMultiConnectionTools(input) {
 	const { registration, connections, allowTools, disallowTools, requireApproval, client, mcpClients, resolverId } = input;
-	const requireApprovalFor = Array.isArray(requireApproval) ? new Set(requireApproval) : void 0;
+	const requireApprovalFor = Array.isArray(requireApproval) ? compileToolMatcher(requireApproval) : void 0;
 	const listToolKey = listConnectionsToolKey(registration.integrationId);
 	const innerAllowTools = allowTools?.filter((name) => name !== listToolKey);
 	const innerDisallowTools = disallowTools?.filter((name) => name !== listToolKey);
@@ -734,7 +858,7 @@ async function buildMcpMultiConnectionTools(input) {
 						id: `mastra-connect-${resolverId}-${registration.integrationId}-${connection.id}`,
 						servers: { [registration.integrationId]: {
 							...transport,
-							...requireApproval === true ? { requireToolApproval: true } : requireApprovalFor ? { requireToolApproval: ({ toolName }) => requireApprovalFor.has(`${registration.integrationId}_${String(toolName)}`) } : {}
+							...requireApproval === true ? { requireToolApproval: true } : requireApprovalFor ? { requireToolApproval: ({ toolName }) => requireApprovalFor(`${registration.integrationId}_${String(toolName)}`) } : {}
 						} }
 					})
 				};
@@ -751,8 +875,8 @@ async function buildMcpMultiConnectionTools(input) {
 		}
 		const catalogUnion = /* @__PURE__ */ new Set();
 		for (const catalog of rawInnerCatalogs.values()) for (const key of Object.keys(catalog)) catalogUnion.add(key);
-		if (requireApprovalFor) {
-			const unknown = [...requireApprovalFor].filter((name) => !catalogUnion.has(name));
+		if (Array.isArray(requireApproval)) {
+			const unknown = expandToolPatterns(requireApproval, [...catalogUnion], `requireApproval for '${registration.integrationId}'`).filter((name) => !catalogUnion.has(name));
 			if (unknown.length > 0) throw new MastraConnectConfigError(`Unknown tool name(s) in requireApproval for '${registration.integrationId}': ${unknown.join(", ")}. Known tools: ${[...catalogUnion].join(", ")}.`);
 		}
 		innerToolsByConnectionId = /* @__PURE__ */ new Map();
@@ -782,7 +906,7 @@ async function buildMcpMultiConnectionTools(input) {
 }
 //#endregion
 //#region src/providers/channels.ts
-function credentialToken$1(credential) {
+function credentialToken(credential) {
 	switch (credential.type) {
 		case "oauth2": return credential.accessToken;
 		case "two_step": return credential.token;
@@ -836,7 +960,7 @@ const CHANNELS$1 = [
 			const mod = await import("@mastra/slack");
 			const safeOptions = stripReservedOptions("slack-channels", options);
 			const tokenResolver = async () => {
-				return credentialToken$1(await runtime.getCredential());
+				return credentialToken(await runtime.getCredential());
 			};
 			return { provider: new mod.SlackProvider({
 				tokenResolver,
@@ -850,7 +974,7 @@ const CHANNELS$1 = [
 			const mod = await import("@mastra/telegram");
 			const safeOptions = stripReservedOptions("telegram", options);
 			const tokenResolver = async () => {
-				return credentialToken$1(await runtime.getCredential());
+				return credentialToken(await runtime.getCredential());
 			};
 			return { provider: new mod.TelegramProvider({
 				tokenResolver,
@@ -891,7 +1015,7 @@ const CHANNELS$1 = [
 			const safeOptions = stripReservedOptions("microsoft-teams", options);
 			const tokenResolver = async (scope) => {
 				const fresh = await runtime.getCredential();
-				if (!(Array.isArray(scope) ? scope : [scope]).includes(mod.TEAMS_DEV_PORTAL_SCOPE)) return credentialToken$1(fresh);
+				if (!(Array.isArray(scope) ? scope : [scope]).includes(mod.TEAMS_DEV_PORTAL_SCOPE)) return credentialToken(fresh);
 				const token = fresh.type === "oauth2" ? fresh.secondaryAccessTokens?.devPortalAccessToken?.accessToken : void 0;
 				if (!token) throw new MastraConnectError("no_active_connection", `Teams connection ${runtime.getConnectionId()} has no Dev Portal token on its credential. Reconnect with an integration that requests the ${mod.TEAMS_DEV_PORTAL_SCOPE} scope.`);
 				return token;
@@ -34618,12 +34742,35 @@ const getCreateIssueMetadataInputSchema = zod.z.object({
 	issuetypeIds: zod.z.array(zod.z.string()).optional().describe("List of issue type IDs to filter by. Example: [\"10000\", \"10001\"]"),
 	expand: zod.z.string().optional().describe("Use expand to include additional information about issue metadata in the response. Supported values: projects, projects.issuetypes, projects.issuetypes.fields")
 });
+const CreateIssueFieldSchema = zod.z.object({
+	required: zod.z.boolean().optional(),
+	schema: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+	name: zod.z.string().optional(),
+	key: zod.z.string().optional(),
+	hasDefaultValue: zod.z.boolean().optional(),
+	operations: zod.z.array(zod.z.string()).optional(),
+	allowedValues: zod.z.array(zod.z.unknown()).optional(),
+	defaultValue: zod.z.unknown().optional(),
+	autoCompleteUrl: zod.z.string().optional()
+});
+const IssueTypeSchema$1 = zod.z.object({
+	id: zod.z.string(),
+	name: zod.z.string(),
+	self: zod.z.string().optional(),
+	description: zod.z.string().optional(),
+	iconUrl: zod.z.string().optional(),
+	avatarId: zod.z.number().optional(),
+	subtask: zod.z.boolean().optional(),
+	hierarchyLevel: zod.z.number().optional(),
+	fields: zod.z.record(zod.z.string(), CreateIssueFieldSchema).optional()
+});
 const ProjectSchema$3 = zod.z.object({
 	id: zod.z.string(),
 	key: zod.z.string(),
 	name: zod.z.string(),
 	self: zod.z.string().optional(),
-	avatarUrls: zod.z.record(zod.z.string(), zod.z.string()).optional()
+	avatarUrls: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+	issuetypes: zod.z.array(IssueTypeSchema$1).optional()
 });
 const ProviderResponseSchema$149 = zod.z.object({ projects: zod.z.array(ProjectSchema$3).optional() });
 const getCreateIssueMetadataOutputSchema = zod.z.object({ projects: zod.z.array(ProjectSchema$3).optional() });
@@ -35743,7 +35890,7 @@ zod.z.object({
 	cloudId: zod.z.string().optional(),
 	baseUrl: zod.z.string().optional()
 });
-const listIssueTypesInputSchema = zod.z.object({});
+const listIssueTypesInputSchema = zod.z.object({ projectId: zod.z.string().optional().describe("Project ID used to list only issue types available in that project.") });
 const IssueTypeSchema = zod.z.object({
 	id: zod.z.string(),
 	name: zod.z.string(),
@@ -35772,7 +35919,7 @@ const AccessibleResourceSchema$1 = zod.z.object({
 function listIssueTypesTool(proxy) {
 	return (0, _mastra_core_tools.createTool)({
 		id: "jira_list_issue_types",
-		description: "List Jira issue types available to the user",
+		description: "List Jira issue types available to the user. Pass projectId to list only the issue types available in that project (recommended before creating an issue).",
 		inputSchema: listIssueTypesInputSchema,
 		outputSchema: listIssueTypesOutputSchema,
 		execute: async (input, { requestContext }) => {
@@ -35807,7 +35954,12 @@ function listIssueTypesTool(proxy) {
 					baseUrl
 				});
 			}
-			const config = {
+			const config = input.projectId ? {
+				endpoint: `/ex/jira/${cloudId}/rest/api/3/issuetype/project`,
+				params: { projectId: input.projectId },
+				headers: { "X-Atlassian-Token": "no-check" },
+				retries: 3
+			} : {
 				endpoint: `/ex/jira/${cloudId}/rest/api/3/issuetype`,
 				headers: { "X-Atlassian-Token": "no-check" },
 				retries: 3
@@ -74096,7 +74248,7 @@ function createWorkosTools(options) {
 * Providers with checked-in HTTP toolsets. MCP-backed providers are discovered
 * from the Platform integration catalog at runtime.
 */
-const TOOLS = [
+const PROVIDERS = [
 	anthropicProvider,
 	clerkProvider,
 	discordProvider,
@@ -74129,27 +74281,16 @@ const TOOLS = [
 	}
 ];
 /**
-* @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 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/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 validateProviderIds(providers) {
+	for (const integrationId of Object.keys(providers ?? {})) if (!INTEGRATION_ID_PATTERN.test(integrationId)) throw new MastraConnectError("invalid_options", `Invalid provider '${integrationId}' in providers option: expected 1-128 letters, numbers, underscores, or hyphens.`);
 }
 function connectionIdEnvVar(integrationId) {
 	return `MASTRA_${integrationId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_CONNECTION_ID`;
@@ -74164,42 +74305,8 @@ function groupByIntegrationId(connections) {
 	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}.`);
-}
-/**
 * Resolves how to configure one provider given its candidate connections:
-*   - An explicit pin (option or env var) forces `single` at that id.
+*   - An explicit pin (`connectionId`) forces `single` at that id.
 *   - Exactly one active connection → `single`.
 *   - Two or more active connections → `multi`; the caller wraps tools with
 *     `connection_name` so the agent chooses per call at execute time.
@@ -74250,12 +74357,12 @@ 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 `TOOLS` registry. MCP providers
+* 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
+* revalidating from the platform every `ttlMs`, so providers connected
+* to (or disconnected from) the project are picked up (or dropped) without a
 * restart.
 *
 * Configuration errors (missing project id, bad ttlMs, malformed integration id,
@@ -74274,11 +74381,14 @@ function tools(options = {}) {
 	const client = resolveClient(options.client);
 	const resolverId = ++nextResolverId;
 	const mcpClients = /* @__PURE__ */ new Map();
-	const integrationOverrides = normalizeIntegrationOverrides(options.integrations);
-	validateIntegrationOverrides(integrationOverrides);
-	validateIntegrationXor(integrationOverrides);
-	validateRequireApproval(integrationOverrides);
-	rejectRemovedAutoApproveTools(integrationOverrides);
+	const normalizedProviders = normalizeProviderOverrides(options.providers);
+	const providerOverrides = normalizedProviders.overrides;
+	validateProviderIds(providerOverrides);
+	validateProviderXor(providerOverrides);
+	validateRequireApproval(providerOverrides);
+	rejectRemovedAutoApproveTools(providerOverrides);
+	if (options.allowTools !== void 0 && options.disallowTools !== void 0) throw new MastraConnectError("invalid_options", "Top-level allowTools and disallowTools are mutually exclusive; set at most one.");
+	if (options.requireApproval !== void 0 && typeof options.requireApproval !== "boolean" && !(Array.isArray(options.requireApproval) && options.requireApproval.every((name) => typeof name === "string"))) throw new MastraConnectError("invalid_options", "Top-level requireApproval must be a boolean or an array of tool keys.");
 	let cache;
 	let inflight;
 	let closing;
@@ -74294,15 +74404,17 @@ function tools(options = {}) {
 		const connections = connectionsResult.value;
 		if (catalogResult.status === "fulfilled") return {
 			connections,
-			catalog: catalogResult.value
+			catalog: catalogResult.value,
+			catalogAvailable: true
 		};
-		const checkedIn = new Set(TOOLS.map((registration) => registration.integrationId));
-		if (connections.some((connection) => connection.status === "active" && !checkedIn.has(connection.integrationId) && !integrationOverrides[connection.integrationId]?.disabled)) throw catalogResult.reason;
+		const checkedIn = new Set(PROVIDERS.map((registration) => registration.integrationId));
+		if (connections.some((connection) => connection.status === "active" && !checkedIn.has(connection.integrationId) && !providerOverrides[connection.integrationId]?.disabled && (normalizedProviders.only === void 0 || normalizedProviders.only.has(connection.integrationId)))) 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.`);
 		return {
 			connections,
-			catalog: []
+			catalog: [],
+			catalogAvailable: false
 		};
 	};
 	/**
@@ -74313,8 +74425,8 @@ function tools(options = {}) {
 		if (closing) return closing.then(refresh);
 		if (!inflight) inflight = (async () => {
 			try {
-				const { connections, catalog } = await loadSnapshotInputs();
-				const snapshot = await mapTools(connections, buildRequests(integrationOverrides, catalog), options, client, mcpClients, resolverId);
+				const { connections, catalog, catalogAvailable } = await loadSnapshotInputs();
+				const snapshot = await mapTools(connections, buildRequests(normalizedProviders, catalog, catalogAvailable), options, client, mcpClients, resolverId);
 				cache = {
 					snapshot,
 					fetchedAt: Date.now()
@@ -74344,10 +74456,7 @@ function tools(options = {}) {
 		}
 		return refresh();
 	};
-	return Object.assign(resolve, {
-		invalidate: () => {
-			cache = void 0;
-		},
+	const resolver = Object.assign(resolve, {
 		refresh,
 		disconnect: () => {
 			closing ??= (async () => {
@@ -74362,28 +74471,75 @@ function tools(options = {}) {
 				}
 			})();
 			return closing;
-		}
+		},
+		with: (extra) => withExtraTools(resolver, extra)
 	});
+	return resolver;
 }
 /**
-* Turns the two accepted `integrations` shapes into the internal Record form.
-* The string-array shorthand (`["linear", "github"]`) becomes
-* `{ linear: {}, github: {} }`; the object form passes through unchanged.
-* Also rejects malformed inputs early (non-string array entries, duplicates)
-* so a bad option throws at tools() time rather than at first refresh.
+* Builds the resolver `.with()` returns: resolutions merge the base
+* resolver's tools with `extra` (extra wins on key collision), cache handles
+* delegate to the base, and further `.with()` calls chain.
 */
-function normalizeIntegrationOverrides(integrations) {
-	if (integrations === void 0) return {};
-	if (Array.isArray(integrations)) {
-		const record = {};
-		for (const entry of integrations) {
-			if (typeof entry !== "string") throw new MastraConnectError("invalid_options", `Invalid integrations entry: expected a string integration id, got ${typeof entry}.`);
-			if (record[entry] !== void 0) throw new MastraConnectError("invalid_options", `Duplicate integration '${entry}' in integrations array.`);
-			record[entry] = {};
-		}
-		return record;
+function withExtraTools(base, extra) {
+	const resolveExtra = typeof extra === "function" ? extra : () => extra;
+	const resolve = async (ctx) => {
+		const [baseTools, extraTools] = await Promise.all([base(ctx), resolveExtra(ctx)]);
+		return {
+			...baseTools,
+			...extraTools
+		};
+	};
+	const resolver = Object.assign(resolve, {
+		refresh: async () => {
+			const [baseTools, extraTools] = await Promise.all([base.refresh(), resolveExtra()]);
+			return {
+				...baseTools,
+				...extraTools
+			};
+		},
+		disconnect: () => base.disconnect(),
+		with: (more) => withExtraTools(resolver, more)
+	});
+	return resolver;
+}
+/**
+* Turns the two accepted `providers` shapes into the internal form. The
+* array form (`["linear", "github"]`) becomes an allowlist with default
+* options; the record form expands boolean shorthands (`true` → `{}`,
+* `false` → an internal exclusion marker). Malformed inputs (non-string
+* array entries, duplicates, non-boolean/non-object record values) throw at
+* tools() time rather than at first refresh.
+*/
+function normalizeProviderOverrides(providers) {
+	if (providers === void 0) return {
+		overrides: {},
+		only: void 0
+	};
+	if (Array.isArray(providers)) {
+		const overrides = {};
+		for (const entry of providers) {
+			if (typeof entry !== "string") throw new MastraConnectError("invalid_options", `Invalid providers entry: expected a string provider id, got ${typeof entry}.`);
+			if (overrides[entry] !== void 0) throw new MastraConnectError("invalid_options", `Duplicate provider '${entry}' in providers array.`);
+			overrides[entry] = {};
+		}
+		return {
+			overrides,
+			only: new Set(Object.keys(overrides))
+		};
 	}
-	return integrations;
+	const overrides = {};
+	for (const [providerId, value] of Object.entries(providers)) {
+		if (value === void 0) continue;
+		if (value === true) overrides[providerId] = {};
+		else if (value === false) overrides[providerId] = { disabled: true };
+		else if (typeof value === "object" && value !== null && !Array.isArray(value)) overrides[providerId] = value;
+		else throw new MastraConnectError("invalid_options", `Invalid providers entry for '${providerId}': expected true, false, or an options object, got ${value === null ? "null" : Array.isArray(value) ? "an array" : typeof value}.`);
+	}
+	return {
+		overrides,
+		only: void 0
+	};
 }
 /**
 * Rejects any provider that sets both `allowTools` and `disallowTools`.
@@ -74391,8 +74547,8 @@ function normalizeIntegrationOverrides(integrations) {
 * runtime guard catches loosely typed inputs (e.g. built from JSON or a
 * `Record<string, unknown>` upstream).
 */
-function validateIntegrationXor(integrations) {
-	for (const [integrationId, providerOptions] of Object.entries(integrations)) {
+function validateProviderXor(providers) {
+	for (const [integrationId, providerOptions] of Object.entries(providers)) {
 		const filters = providerOptions;
 		if (filters.allowTools !== void 0 && filters.disallowTools !== void 0) throw new MastraConnectError("invalid_options", `Invalid options for '${integrationId}': allowTools and disallowTools are mutually exclusive; set at most one.`);
 	}
@@ -74404,8 +74560,8 @@ function validateIntegrationXor(integrations) {
 * approval on MCP providers silently (and crash the HTTP path into
 * warn-and-skip) instead of gating tools as the author intended.
 */
-function validateRequireApproval(integrations) {
-	for (const [integrationId, providerOptions] of Object.entries(integrations)) {
+function validateRequireApproval(providers) {
+	for (const [integrationId, providerOptions] of Object.entries(providers)) {
 		const requireApproval = providerOptions.requireApproval;
 		if (requireApproval === void 0 || typeof requireApproval === "boolean") continue;
 		if (Array.isArray(requireApproval) && requireApproval.every((name) => typeof name === "string")) continue;
@@ -74418,12 +74574,12 @@ function validateRequireApproval(integrations) {
 * carrying this key would otherwise be ignored silently and its tools would
 * run without the prompts the author expected.
 */
-function rejectRemovedAutoApproveTools(integrations) {
-	for (const [integrationId, providerOptions] of Object.entries(integrations)) if ("autoApproveTools" in providerOptions) throw new MastraConnectError("invalid_options", `Invalid options for '${integrationId}': autoApproveTools was removed. Tools no longer require approval by default; opt in with requireApproval: true or a list of tool keys to gate.`);
+function rejectRemovedAutoApproveTools(providers) {
+	for (const [integrationId, providerOptions] of Object.entries(providers)) if ("autoApproveTools" in providerOptions) throw new MastraConnectError("invalid_options", `Invalid options for '${integrationId}': autoApproveTools was removed. Tools no longer require approval by default; opt in with requireApproval: true or a list of tool keys to gate.`);
 }
-function buildRequests(integrations, catalog) {
-	const overrides = integrations;
-	const registrations = new Map(TOOLS.map((registration) => [registration.integrationId, registration]));
+function buildRequests(providers, catalog, catalogAvailable) {
+	const { overrides, only } = providers;
+	const registrations = new Map(PROVIDERS.map((registration) => [registration.integrationId, registration]));
 	const catalogIds = new Set(catalog.map((integration) => integration.id));
 	for (const integration of catalog) {
 		if (!integration.capabilities.mcp) continue;
@@ -74433,9 +74589,14 @@ function buildRequests(integrations, catalog) {
 			transport: "mcp"
 		});
 	}
-	for (const integrationId of Object.keys(overrides)) if (!registrations.has(integrationId) && !catalogIds.has(integrationId)) console.warn(`[@mastra/connect] Ignoring unknown integration override '${integrationId}'.`);
+	const unknown = Object.keys(overrides).filter((integrationId) => !registrations.has(integrationId) && !catalogIds.has(integrationId) && !overrides[integrationId]?.disabled);
+	if (unknown.length > 0) {
+		if (catalogAvailable) throw new MastraConnectConfigError(`Unknown provider${unknown.length > 1 ? "s" : ""} in the providers option: ${unknown.map((id) => `'${id}'`).join(", ")}. Expected a checked-in provider id or a platform catalog integration id.`);
+		for (const integrationId of unknown) console.warn(`[@mastra/connect] Platform catalog unavailable; cannot verify provider '${integrationId}'. Skipping it this resolution.`);
+	}
 	const requests = [];
 	for (const registration of registrations.values()) {
+		if (only !== void 0 && !only.has(registration.integrationId)) continue;
 		const providerOptions = overrides[registration.integrationId] ?? {};
 		if (providerOptions.disabled) continue;
 		requests.push({
@@ -74451,6 +74612,7 @@ async function mapTools(connections, requests, options, client, mcpClients, reso
 	const activeMcpKeys = /* @__PURE__ */ new Set();
 	const result = {};
 	const toolOwners = /* @__PURE__ */ new Map();
+	const matchedDefaultEntries = /* @__PURE__ */ new Set();
 	for (const request of requests) {
 		const integrationId = request.registration.integrationId;
 		let providerTools;
@@ -74510,6 +74672,11 @@ async function mapTools(connections, requests, options, client, mcpClients, reso
 			console.warn(`[@mastra/connect] Skipping ${integrationId}: ${error instanceof Error ? error.message : String(error)}`);
 			continue;
 		}
+		if (!(request.options.allowTools !== void 0 || request.options.disallowTools !== void 0) && (options.allowTools !== void 0 || options.disallowTools !== void 0)) providerTools = applyDefaultFilter(providerTools, options, integrationId, matchedDefaultEntries);
+		if (request.options.requireApproval === void 0 && options.requireApproval !== void 0) {
+			const policy = options.requireApproval;
+			if (policy !== false) applyDefaultRequireApproval(providerTools, policy, integrationId, matchedDefaultEntries);
+		}
 		for (const toolKey of Object.keys(providerTools)) {
 			const existingOwner = toolOwners.get(toolKey);
 			if (existingOwner) throw new MastraConnectError("invalid_options", `Duplicate tool key '${toolKey}' from providers '${existingOwner}' and '${integrationId}'.`);
@@ -74517,13 +74684,78 @@ async function mapTools(connections, requests, options, client, mcpClients, reso
 		}
 		Object.assign(result, providerTools);
 	}
+	if (Object.keys(result).length > 0) {
+		const defaultEntries = [
+			...options.allowTools ?? [],
+			...options.disallowTools ?? [],
+			...Array.isArray(options.requireApproval) ? options.requireApproval : []
+		];
+		for (const entry of defaultEntries) if (!matchedDefaultEntries.has(entry)) console.warn(`[@mastra/connect] Top-level entry '${entry}' matched no tools on any resolved provider.`);
+	}
 	const staleClients = Array.from(mcpClients.entries()).filter(([key]) => !activeMcpKeys.has(key));
 	for (const [key] of staleClients) mcpClients.delete(key);
 	await Promise.allSettled(staleClients.map(([, entry]) => entry.client.disconnect()));
 	return result;
 }
 /**
-* Extracts whichever provider tool filter is set. Since `ToolsIntegrationOptions`
+* Applies the top-level default filter to a provider that set no filter of
+* its own. Lenient by design: the provider set is live, so a default entry
+* that matches nothing on this provider simply does not apply here. Entries
+* that match are recorded in `matchedEntries` so mapTools can warn about
+* defaults that matched nothing anywhere. The synthetic
+* `<provider>__list_connections` wrapper is never filtered by defaults,
+* matching the per-provider multi-connection behavior.
+*/
+function applyDefaultFilter(providerTools, defaults, integrationId, matchedEntries) {
+	const listToolKey = listConnectionsToolKey(integrationId);
+	const matchers = (defaults.allowTools ?? defaults.disallowTools ?? []).map((entry) => ({
+		entry,
+		matches: compileToolMatcher([entry])
+	}));
+	const filtered = {};
+	for (const [key, tool] of Object.entries(providerTools)) {
+		if (key === listToolKey) {
+			filtered[key] = tool;
+			continue;
+		}
+		let matchedAny = false;
+		for (const { entry, matches } of matchers) if (matches(key)) {
+			matchedEntries.add(entry);
+			matchedAny = true;
+		}
+		if (defaults.allowTools !== void 0 ? matchedAny : !matchedAny) filtered[key] = tool;
+	}
+	return filtered;
+}
+/**
+* Applies the top-level default `requireApproval` policy to a provider that
+* set no policy of its own. `true` gates every tool except the synthetic
+* `<provider>__list_connections` wrapper; an array gates matching keys with
+* the same lenient semantics as {@link applyDefaultFilter}.
+*/
+function applyDefaultRequireApproval(providerTools, policy, integrationId, matchedEntries) {
+	const listToolKey = listConnectionsToolKey(integrationId);
+	if (policy === true) {
+		for (const [key, tool] of Object.entries(providerTools)) {
+			if (key === listToolKey) continue;
+			tool.requireApproval = true;
+		}
+		return;
+	}
+	const matchers = policy.map((entry) => ({
+		entry,
+		matches: compileToolMatcher([entry])
+	}));
+	for (const [key, tool] of Object.entries(providerTools)) {
+		if (key === listToolKey) continue;
+		for (const { entry, matches } of matchers) if (matches(key)) {
+			matchedEntries.add(entry);
+			tool.requireApproval = true;
+		}
+	}
+}
+/**
+* Extracts whichever provider tool filter is set. Since `ToolsProviderOptions`
 * is an XOR union and tools() validates co-occurrence up front, at most one
 * of the two will ever be defined here.
 */
@@ -74535,14 +74767,16 @@ function providerFilterOptions(options) {
 * toolset by marking the selected tools. `true` gates every provider tool
 * (but never the synthetic `<provider>__list_connections` wrapper tool,
 * matching the MCP paths, where only server-discovered tools are gated);
-* an array gates the listed keys and rejects unknown names with the same
-* `invalid_options` error MCP discovery raises, so a typo never silently
-* widens access.
+* an array gates the listed keys — entries containing `*` are globs,
+* expanded against the provider tools minus the synthetic wrapper so a
+* broad glob behaves like `true` — and rejects unknown names and dead
+* globs with the same `invalid_options` error MCP discovery raises, so a
+* typo never silently widens access.
 */
 function applyProxyRequireApproval(providerTools, integrationId, requireApproval, excludeKeys = []) {
 	if (!requireApproval) return;
+	const excluded = new Set(excludeKeys);
 	if (requireApproval === true) {
-		const excluded = new Set(excludeKeys);
 		for (const [toolKey, tool] of Object.entries(providerTools)) {
 			if (excluded.has(toolKey)) continue;
 			tool.requireApproval = true;
@@ -74550,13 +74784,14 @@ function applyProxyRequireApproval(providerTools, integrationId, requireApproval
 		return;
 	}
 	const known = Object.keys(providerTools);
-	const unknown = requireApproval.filter((name) => !known.includes(name));
+	const expanded = expandToolPatterns(requireApproval, known.filter((key) => !excluded.has(key)), `requireApproval for '${integrationId}'`);
+	const unknown = expanded.filter((name) => !known.includes(name));
 	if (unknown.length > 0) throw new MastraConnectConfigError(`Unknown tool name(s) in requireApproval for '${integrationId}': ${unknown.join(", ")}. Known tools: ${known.join(", ")}.`);
-	for (const name of requireApproval) providerTools[name].requireApproval = true;
+	for (const name of expanded) providerTools[name].requireApproval = true;
 }
 async function discoverMcpTools(input) {
 	const { registration, connectionId, allowTools, disallowTools, requireApproval, client, mcpClients, resolverId } = input;
-	const requireApprovalFor = Array.isArray(requireApproval) ? new Set(requireApproval) : void 0;
+	const requireApprovalFor = Array.isArray(requireApproval) ? compileToolMatcher(requireApproval) : void 0;
 	const cacheKey = `${registration.integrationId}::${connectionId}`;
 	let entry = mcpClients.get(cacheKey);
 	if (!entry) {
@@ -74568,7 +74803,7 @@ async function discoverMcpTools(input) {
 				id: `mastra-connect-${resolverId}-${registration.integrationId}-${connectionId}`,
 				servers: { [registration.integrationId]: {
 					...transport,
-					...requireApproval === true ? { requireToolApproval: true } : requireApprovalFor ? { requireToolApproval: ({ toolName }) => requireApprovalFor.has(`${registration.integrationId}_${String(toolName)}`) } : {}
+					...requireApproval === true ? { requireToolApproval: true } : requireApprovalFor ? { requireToolApproval: ({ toolName }) => requireApprovalFor(`${registration.integrationId}_${String(toolName)}`) } : {}
 				} }
 			})
 		};
@@ -74577,8 +74812,8 @@ async function discoverMcpTools(input) {
 	const discovery = await entry.client.listToolsWithErrors();
 	const error = discovery.errors[registration.integrationId];
 	if (error) throw new Error(`MCP tool discovery failed: ${error}`);
-	if (requireApprovalFor) {
-		const unknown = [...requireApprovalFor].filter((name) => !(name in discovery.tools));
+	if (Array.isArray(requireApproval)) {
+		const unknown = expandToolPatterns(requireApproval, Object.keys(discovery.tools), `requireApproval for '${registration.integrationId}'`).filter((name) => !(name in discovery.tools));
 		if (unknown.length > 0) throw new MastraConnectConfigError(`Unknown tool name(s) in requireApproval for '${registration.integrationId}': ${unknown.join(", ")}. Known tools: ${Object.keys(discovery.tools).join(", ")}.`);
 	}
 	return applyToolFilter(discovery.tools, {
@@ -74587,23 +74822,6 @@ async function discoverMcpTools(input) {
 	});
 }
 //#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);
-}
-//#endregion
 //#region src/channels.ts
 const DEFAULT_TTL_MS = 3e4;
 /** Minimum wait after a failed platform fetch before another background revalidation. */
@@ -74616,7 +74834,7 @@ const FAILURE_COOLDOWN_MS = 3e4;
 * Discord) are constructed once, up front and credential-less, so their
 * webhook/OAuth routes can mount at Mastra construction. Each resolution
 * fetches the project's connections and late-binds credentials into the live
-* instances: integrations with an active connection appear in the resolved
+* instances: providers with an active connection appear in the resolved
 * map, others don't — so connecting a new channel on the platform takes
 * effect without redeploying the app.
 *
@@ -74641,12 +74859,17 @@ async 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 { overrides: providerOverrides, only } = normalizeChannelProviders(options.providers);
+	validateProviderIds(providerOverrides);
+	const knownChannelIds = new Set(CHANNELS.map((registration) => registration.integrationId));
+	const unknownChannelIds = Object.keys(providerOverrides).filter((integrationId) => !knownChannelIds.has(integrationId) && !providerOverrides[integrationId]?.disabled);
+	if (unknownChannelIds.length > 0) throw new MastraConnectError("invalid_options", `Unknown channel${unknownChannelIds.length > 1 ? "s" : ""} in the providers option: ${unknownChannelIds.map((id) => `'${id}'`).join(", ")}. Known channels: ${[...knownChannelIds].join(", ")}.`);
 	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
 	const client = resolveClient(options.client);
 	const states = [];
 	for (const registration of CHANNELS) {
-		const overrides = options.integrations?.[registration.integrationId] ?? {};
+		if (only !== void 0 && !only.has(registration.integrationId)) continue;
+		const overrides = providerOverrides[registration.integrationId] ?? {};
 		if (overrides.disabled) continue;
 		const state = {
 			registration,
@@ -74699,7 +74922,7 @@ async function channels(options = {}) {
 		}
 		for (const state of states) {
 			const integrationId = state.registration.integrationId;
-			const overrides = options.integrations?.[integrationId] ?? {};
+			const overrides = providerOverrides[integrationId] ?? {};
 			const candidates = byIntegrationId.get(integrationId) ?? [];
 			const connectionId = candidates.length === 0 ? void 0 : selectChannelConnection(integrationId, overrides.connectionId, candidates);
 			state.connectionId = connectionId;
@@ -74746,9 +74969,6 @@ async function channels(options = {}) {
 	};
 	const invocable = ((_context) => resolve());
 	invocable.getRoutes = () => states.flatMap((state) => state.instance.provider.getRoutes());
-	invocable.invalidate = () => {
-		cache = void 0;
-	};
 	invocable.refresh = refresh;
 	invocable.disconnect = async () => {
 		cache = void 0;
@@ -74756,15 +74976,73 @@ async function channels(options = {}) {
 	return invocable;
 }
 /**
+* Friendly channel-key aliases. The Slack channel is keyed `slack-channels`
+* on the platform (plain `slack` names the Slack tools provider), but inside
+* a channels() config `slack` is unambiguous — accept it and canonicalize to
+* the platform key for registration and connection lookup.
+*/
+const CHANNEL_KEY_ALIASES = { slack: "slack-channels" };
+const canonicalChannelId = (id) => CHANNEL_KEY_ALIASES[id] ?? id;
+/** Throws when two option keys (e.g. `slack` and `slack-channels`) name the same channel. */
+function rejectAliasCollision(sourceKeys, canonical, key) {
+	const existing = sourceKeys[canonical];
+	if (existing === void 0) return;
+	throw new MastraConnectError("invalid_options", existing === key ? `Duplicate provider '${key}' in providers array.` : `Both '${existing}' and '${key}' name the '${canonical}' channel in the providers option; use one key.`);
+}
+/**
+* Turns the two accepted `providers` shapes into the internal form, mirroring
+* `tools()`. The array form becomes an allowlist with default options; the
+* record form expands boolean shorthands (`true` → `{}`, `false` → an
+* internal exclusion marker). Alias keys canonicalize first, so `slack` and
+* `slack-channels` configure the same channel (and collide loudly). Malformed
+* inputs throw at channels() time.
+*/
+function normalizeChannelProviders(providers) {
+	if (providers === void 0) return {
+		overrides: {},
+		only: void 0
+	};
+	const sourceKeys = {};
+	if (Array.isArray(providers)) {
+		const overrides = {};
+		for (const entry of providers) {
+			if (typeof entry !== "string") throw new MastraConnectError("invalid_options", `Invalid providers entry: expected a string channel id, got ${typeof entry}.`);
+			const canonical = canonicalChannelId(entry);
+			rejectAliasCollision(sourceKeys, canonical, entry);
+			sourceKeys[canonical] = entry;
+			overrides[canonical] = {};
+		}
+		return {
+			overrides,
+			only: new Set(Object.keys(overrides))
+		};
+	}
+	const overrides = {};
+	for (const [providerId, value] of Object.entries(providers)) {
+		if (value === void 0) continue;
+		const canonical = canonicalChannelId(providerId);
+		rejectAliasCollision(sourceKeys, canonical, providerId);
+		sourceKeys[canonical] = providerId;
+		if (value === true) overrides[canonical] = {};
+		else if (value === false) overrides[canonical] = { disabled: true };
+		else if (typeof value === "object" && value !== null && !Array.isArray(value)) overrides[canonical] = value;
+		else throw new MastraConnectError("invalid_options", `Invalid providers entry for '${providerId}': expected true, false, or an options object, got ${value === null ? "null" : Array.isArray(value) ? "an array" : typeof value}.`);
+	}
+	return {
+		overrides,
+		only: void 0
+	};
+}
+/**
 * Selects the connection `channels()` should use for one provider.
 *
-* - Pinned `connectionId` (from `integrations.<id>.connectionId`) wins, but is
+* - Pinned `connectionId` (from `providers.<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
+*   pin explicitly with `providers.<id>.connectionId` when the deterministic
 *   choice matters.
 */
 function selectChannelConnection(integrationId, pinnedId, candidates) {
@@ -74793,7 +75071,7 @@ function selectChannelConnection(integrationId, pinnedId, candidates) {
 	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.`);
+	console.warn(`[@mastra/connect] ${integrationId} channel: found ${active.length} active connections; using ${chosen}. Ignoring ${others}. Pin one with providers.${integrationId}.connectionId to silence this warning.`);
 	return chosen;
 }
 //#endregion
@@ -74806,123 +75084,11 @@ async function credential(connectionId, options) {
 	return getCredential(resolveClient(options?.client), connectionId);
 }
 //#endregion
-//#region src/environment.ts
-function credentialToken(credential) {
-	if (credential.type === "oauth2") return credential.accessToken;
-	if (credential.type === "two_step") return credential.token;
-	return 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
 exports.CHANNELS = CHANNELS;
 exports.MastraConnectError = MastraConnectError;
 exports.PROVIDERS = PROVIDERS;
-exports.TOOLS = TOOLS;
-exports.applyAllowTools = applyAllowTools;
 exports.channels = channels;
-exports.connect = connect;
 exports.credential = credential;
-exports.defineProxyTool = defineProxyTool;
-exports.environment = environment;
-exports.findChannelRegistration = findChannelRegistration;
-exports.findRegistration = findRegistration;
-exports.resolveConnectionId = resolveConnectionId;
 exports.tools = tools;
 
 //# sourceMappingURL=index.cjs.map