@mastra/discord 1.2.1 → 1.3.0-alpha.1

package/dist/index.js

@@ -130,6 +130,37 @@ async function guildHealthCheck(botToken, guildId, apiBaseUrl = DISCORD_API_BASE
 	}
 	throw new Error(`Discord guild lookup failed for "${guildId}": ${await describeError(response)}`);
 }
+/** Guilds-per-page for `GET /users/@me/guilds` (Discord's documented maximum). */
+const GUILD_PAGE_LIMIT = 200;
+/**
+* Pages we're willing to walk when listing the bot's guilds. The listing feeds
+* the pending-install snapshot diff, whose multiple-new-guilds guard keeps an
+* *incomplete* listing safe (reconcile just stays pending) — so a hard cap is
+* preferable to an unbounded walk on a bot in thousands of guilds.
+*/
+const GUILD_PAGE_MAX_PAGES = 10;
+/**
+* The ids of every guild the bot is a member of, via `GET /users/@me/guilds`
+* (Bot auth), following `after`-cursor pagination. Returns `null` instead of a
+* partial listing when the bot is in more guilds than {@link GUILD_PAGE_MAX_PAGES}
+* covers — callers diffing snapshots must not mistake a truncated page for the
+* full membership. Throws on request failure.
+*
+* @see https://discord.com/developers/docs/resources/user#get-current-user-guilds
+*/
+async function listBotGuildIds(botToken, apiBaseUrl = DISCORD_API_BASE_URL) {
+	const ids = [];
+	let after;
+	for (let page = 0; page < GUILD_PAGE_MAX_PAGES; page++) {
+		const response = await discordRequest(botToken, "GET", `/users/@me/guilds${`?limit=${GUILD_PAGE_LIMIT}${after ? `&after=${after}` : ""}`}`, apiBaseUrl);
+		if (!response.ok) throw new Error(`Discord guild listing failed: ${await describeError(response)}`);
+		const batch = await response.json();
+		for (const guild of batch) ids.push(guild.id);
+		if (batch.length < GUILD_PAGE_LIMIT) return ids;
+		after = batch[batch.length - 1].id;
+	}
+	return null;
+}
 /** Map normalized commands to the Discord bulk-overwrite `CHAT_INPUT` payload. */
 function toCommandPayload(commands) {
 	return commands.map((c) => ({
@@ -269,6 +300,88 @@ function hashCommands(commands) {
 	}));
 	return createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, 16);
 }
+/**
+* A session that ends sooner than this is treated as a failed connect. The
+* adapter resolves login failures as if the session ended cleanly, so elapsed
+* time is the only signal that distinguishes "ran fine until the duration
+* elapsed / Discord closed us" from "IDENTIFY was rejected instantly".
+*/
+const HEALTHY_SESSION_MS = 60 * 1e3;
+/** First retry delay after a failed connect; doubles up to {@link MAX_BACKOFF_MS}. */
+const INITIAL_BACKOFF_MS = 5 * 1e3;
+/** Retry delay ceiling. */
+const MAX_BACKOFF_MS = 900 * 1e3;
+/** Pause between healthy sessions — a scheduled rollover, not a failure. */
+const RECONNECT_DELAY_MS = 1e3;
+/**
+* Run Gateway sessions back-to-back until `signal` aborts or the bot token is
+* confirmed revoked. Resolves when the loop stops; never rejects.
+*/
+async function runGatewayLoop(deps, signal) {
+	const sessionMs = deps.sessionMs ?? 864e5;
+	let backoffMs = INITIAL_BACKOFF_MS;
+	let consecutiveFailures = 0;
+	while (!signal.aborted) {
+		const startedAt = Date.now();
+		try {
+			let settle;
+			let fail;
+			const done = new Promise((resolve, reject) => {
+				settle = resolve;
+				fail = reject;
+			});
+			let sessionDelivered = false;
+			const response = await deps.startSession({ waitUntil: (promise) => {
+				sessionDelivered = true;
+				promise.then(() => settle(), (err) => fail(err));
+			} }, sessionMs, signal);
+			if (!response.ok || !sessionDelivered) throw new Error(`Gateway session refused (status ${response.status})`);
+			await done;
+		} catch (err) {
+			deps.log("error", `Gateway session error: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (signal.aborted) return;
+		const elapsedMs = Date.now() - startedAt;
+		if (elapsedMs >= 6e4) {
+			backoffMs = INITIAL_BACKOFF_MS;
+			consecutiveFailures = 0;
+			deps.log("info", "Gateway session ended; reconnecting");
+			await sleep(RECONNECT_DELAY_MS, signal);
+			continue;
+		}
+		consecutiveFailures += 1;
+		let check;
+		try {
+			check = await deps.checkToken();
+		} catch {
+			check = "unreachable";
+		}
+		if (signal.aborted) return;
+		if (check === "invalid") {
+			deps.log("error", "Discord rejected the bot token (401); Gateway reconnection is parked until configure() supplies new credentials. Reset tokens must be rotated in the Discord Developer Portal and updated wherever this provider gets its credentials.");
+			return;
+		}
+		if (consecutiveFailures === 3) deps.log("error", `Gateway sessions keep ending within ${HEALTHY_SESSION_MS / 1e3}s of starting. The token checks out over REST, so the usual cause is a rejected IDENTIFY: enable the "Message Content Intent" (a privileged intent) for this app in the Discord Developer Portal, or set gateway: false for an interactions-only deployment.`);
+		deps.log("warn", `Gateway session ended after ${Math.round(elapsedMs / 1e3)}s; retrying in ${Math.round(backoffMs / 1e3)}s`);
+		await sleep(backoffMs, signal);
+		backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+	}
+}
+/** Abortable sleep: resolves early (never rejects) when the signal fires. */
+function sleep(ms, signal) {
+	if (signal.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
 //#endregion
 //#region src/crypto.ts
 /**
@@ -430,7 +543,11 @@ var DiscordInstallStore = class {
 			guildIds: install.guildIds,
 			displayName: install.displayName,
 			commands: install.commands,
-			commandVersions: install.commandVersions
+			commandVersions: install.commandVersions,
+			guildSnapshot: install.guildSnapshot,
+			snapshotAt: install.snapshotAt?.toISOString(),
+			snapshotApplicationId: install.snapshotApplicationId,
+			targetGuildId: install.targetGuildId
 		};
 		return {
 			id: install.id,
@@ -454,7 +571,11 @@ var DiscordInstallStore = class {
 			displayName: data.displayName,
 			commands: data.commands,
 			commandVersions: data.commandVersions,
-			installedAt: record.createdAt
+			installedAt: record.createdAt,
+			guildSnapshot: data.guildSnapshot,
+			snapshotAt: data.snapshotAt ? new Date(data.snapshotAt) : void 0,
+			snapshotApplicationId: data.snapshotApplicationId,
+			targetGuildId: data.targetGuildId
 		};
 	}
 };
@@ -469,14 +590,88 @@ function toInstallationInfo(install) {
 		installedAt: install.installedAt
 	};
 }
+/**
+* Whether an install's invite flow is still *live*: started against the
+* current application and within {@link SNAPSHOT_TTL_MS}. Deliberately
+* independent of whether the baseline fetch succeeded — a live flow with a
+* missing baseline still poisons attribution (see {@link planReconcile}),
+* while rows from before these fields existed (no `snapshotAt`) are treated
+* as not live and fall back to first-interaction activation.
+*/
+function isInviteFlowLive(installation, applicationId, now) {
+	return installation.status === "pending" && installation.snapshotApplicationId === applicationId && installation.snapshotAt != null && now.getTime() - installation.snapshotAt.getTime() <= 18e5;
+}
+/**
+* Whether a pending install can reconcile at all: a live invite flow (see
+* {@link isInviteFlowLive}) *with* a membership baseline to diff against.
+* Used as a cheap pre-check before the membership fetch.
+*/
+function hasReconcilableSnapshot(installation, applicationId, now) {
+	return installation.guildSnapshot != null && isInviteFlowLive(installation, applicationId, now);
+}
+/**
+* Decide which pending installs the completed-invite reconcile pass may
+* activate, and on which guild. Pure claim analysis over plain data — all
+* store reads, membership fetches, and activations happen in the caller
+* ({@link DiscordProvider.reconcileInstallation}).
+*
+* Rules, in order:
+* - Only installs with a live invite flow ({@link isInviteFlowLive}) take part.
+*   Expired/foreign-app baselines are ignored (first interaction remains their
+*   activation path), as are legacy rows without snapshot metadata.
+* - A live flow whose baseline fetch failed at connect time poisons the whole
+*   pass: any new guild might be ITS invite landing, so nothing is attributed.
+* - A guild any install already lists is owned and never claimed — it can
+*   still look "new" relative to a stale baseline.
+* - An install with an explicit {@link DiscordInstallation.targetGuildId}
+*   claims *only* that guild. The narrowing happens before claims are tallied,
+*   so a targeted install never contests a guild it would refuse anyway — but
+*   its target, if new, still blocks other installs from taking it.
+* - An install activates only on exactly one new guild, claimed by no other
+*   live install. Zero or multiple candidates, or a contested guild, stay
+*   pending and retry on the next pass.
+*/
+function planReconcile(input) {
+	const { installations, currentGuildIds, applicationId, now } = input;
+	const live = installations.filter((i) => isInviteFlowLive(i, applicationId, now));
+	const claimants = live.filter((i) => i.guildSnapshot != null);
+	if (claimants.length === 0) return [];
+	if (claimants.length !== live.length) return [];
+	const owned = new Set(installations.flatMap((i) => i.guildIds));
+	const diffs = claimants.map((installation) => {
+		const snapshot = new Set(installation.guildSnapshot);
+		let newGuilds = currentGuildIds.filter((id) => !snapshot.has(id) && !owned.has(id));
+		if (installation.targetGuildId != null) newGuilds = newGuilds.includes(installation.targetGuildId) ? [installation.targetGuildId] : [];
+		return {
+			installation,
+			newGuilds
+		};
+	});
+	const claims = /* @__PURE__ */ new Map();
+	for (const { newGuilds } of diffs) for (const id of newGuilds) claims.set(id, (claims.get(id) ?? 0) + 1);
+	const activations = [];
+	for (const { installation, newGuilds } of diffs) {
+		const guildId = newGuilds.length === 1 ? newGuilds[0] : void 0;
+		if (guildId == null || claims.get(guildId) > 1) continue;
+		activations.push({
+			installationId: installation.id,
+			agentId: installation.agentId,
+			webhookId: installation.webhookId,
+			guildId
+		});
+	}
+	return activations;
+}
 //#endregion
 //#region src/discord-provider.ts
 /**
 * Resolve the per-adapter config the provider applies to the Discord entry in
 * `AgentChannels.adapters`. Discord has native embeds + action-row buttons, so
 * `toolDisplay` defaults to `'cards'` (unlike Telegram's `'text'`); `streaming`
-* post-and-edits the interaction followup; `gateway` (default `true`) makes core
-* own the DM/mention Gateway reconnection loop.
+* post-and-edits the interaction followup; `gateway` (default `true`) makes the
+* **provider** run the DM/mention Gateway reconnection loop. (The adapter entry
+* handed to `AgentChannels` always carries `gateway: false` — core's loop must
+* never start; see `#createAgentChannels`.)
 */
 function resolveDiscordAdapterConfig(config) {
 	return {
@@ -500,11 +695,15 @@ function resolveDiscordAdapterConfig(config) {
 * member) or lazily off the first inbound interaction's authoritative `guild_id`
 * (see {@link activateGuild}).
 *
-* **Gateway is core's job.** The mounted interactions route only ever receives
-* HTTP Interactions (PING, slash commands, buttons). DMs / @mentions / reactions
-* arrive over the Gateway WebSocket, whose reconnection loop core owns: setting
-* `gateway: true` (default) on the adapter entry is enough — the wrapper never
-* calls `startGatewayListener` or runs a reconnect loop.
+* **Gateway is the provider's job.** The mounted interactions route only ever
+* receives HTTP Interactions (PING, slash commands, buttons). DMs / @mentions /
+* reactions arrive over the Gateway WebSocket, whose reconnection loop the
+* provider owns ({@link #startGatewayLoop} → `./gateway-loop`): one abortable
+* loop per installation, exponential backoff on failed connects, parked on a
+* revoked token. Core's `AgentChannels` loop is explicitly disabled
+* (`gateway: false` on the adapter entry) — it reconnects with no backoff and
+* cannot be stopped, which is how a failing IDENTIFY once tripped Discord's
+* 1000-connect abuse limit and got the bot token force-reset.
 *
 * Implemented (issues `mastra-discord-13x.2` + `.3`): the app-config +
 * guild-keyed install store, `connect()`/`disconnect()`, OAuth2 invite-URL
@@ -518,6 +717,15 @@ var DiscordProvider = class {
 	#store;
 	/** Live adapters, keyed by installation id (one per agent; all share the app's bot token). */
 	#adapters = /* @__PURE__ */ new Map();
+	/**
+	* Live Gateway reconnect loops, keyed by installation id. Aborting a
+	* controller ends the loop and destroys its discord.js client. Exactly one
+	* loop may exist per installation — {@link #startGatewayLoop} aborts any
+	* predecessor, so credential rotations and adapter rebuilds can't leak loops
+	* that keep IDENTIFYing with stale tokens (Discord force-resets the bot
+	* token past ~1000 connects in a short window).
+	*/
+	#gatewayLoops = /* @__PURE__ */ new Map();
 	/** Cached sync view of whether the app is configured (for {@link getInfo}). */
 	#configured = false;
 	#initPromise = null;
@@ -564,6 +772,7 @@ var DiscordProvider = class {
 			this.#storeIsFallback = false;
 		}
 		if (isNewInstance) {
+			this.#stopAllGatewayLoops();
 			this.#adapters.clear();
 			this.#configured = this.#hasSuppliedCredentials();
 		}
@@ -661,6 +870,7 @@ var DiscordProvider = class {
 				app: void 0
 			};
 			this.#configured = false;
+			this.#stopAllGatewayLoops();
 			this.#adapters.clear();
 			this.#initPromise = null;
 			return;
@@ -696,6 +906,7 @@ var DiscordProvider = class {
 			if (merged.botToken && merged.publicKey && merged.applicationId) await store.saveAppConfig(merged);
 		}
 		const wasInitialized = this.#initPromise !== null;
+		this.#stopAllGatewayLoops();
 		this.#adapters.clear();
 		this.#initPromise = null;
 		if (wasInitialized) await this.initialize();
@@ -726,39 +937,69 @@ var DiscordProvider = class {
 		const installedAt = existing?.installedAt ?? /* @__PURE__ */ new Date();
 		const commands = normalizeCommands(options.commands ?? this.#config.commands ?? DEFAULT_COMMANDS);
 		if (options.guildId && await guildHealthCheck(app.botToken, options.guildId, this.#apiBaseUrl())) {
-			const installation = {
+			const guildId = options.guildId;
+			return await this.#enqueueWebhookTask(webhookId, async () => {
+				const fresh = existing ? await store.getByWebhookId(webhookId) : null;
+				if (fresh?.status === "active") return {
+					type: "immediate",
+					installationId: fresh.id
+				};
+				const installation = {
+					id: installationId,
+					agentId,
+					webhookId,
+					status: "active",
+					guildIds: [guildId],
+					displayName,
+					commands: commands.length ? commands : void 0,
+					commandVersions: fresh?.commandVersions ?? existing?.commandVersions,
+					installedAt
+				};
+				await store.save(installation);
+				await this.#registerCommands(app, installation, guildId);
+				await this.#activateInstallation(installation);
+				this.#configured = true;
+				await this.#config.onInstall?.(installation);
+				return {
+					type: "immediate",
+					installationId
+				};
+			});
+		}
+		const outcome = await this.#enqueueWebhookTask(webhookId, async () => {
+			const fresh = existing ? await store.getByWebhookId(webhookId) : null;
+			if (fresh?.status === "active") return {
+				type: "immediate",
+				installationId: fresh.id
+			};
+			const base = fresh ?? existing;
+			const now = /* @__PURE__ */ new Date();
+			let guildSnapshot = base?.guildSnapshot != null && base.snapshotApplicationId === app.applicationId && base.snapshotAt != null && now.getTime() - base.snapshotAt.getTime() <= 18e5 ? base.guildSnapshot : void 0;
+			if (!guildSnapshot) try {
+				guildSnapshot = await listBotGuildIds(app.botToken, this.#apiBaseUrl()) ?? void 0;
+			} catch (err) {
+				console.warn("[Discord] Could not snapshot guild membership for pending install:", err);
+			}
+			const pending = {
 				id: installationId,
 				agentId,
 				webhookId,
-				status: "active",
-				guildIds: [options.guildId],
+				status: "pending",
+				guildIds: base?.guildIds ?? [],
 				displayName,
 				commands: commands.length ? commands : void 0,
-				commandVersions: existing?.commandVersions,
-				installedAt
-			};
-			await store.save(installation);
-			await this.#registerCommands(app, installation, options.guildId);
-			await this.#activateInstallation(installation);
-			this.#configured = true;
-			await this.#config.onInstall?.(installation);
-			return {
-				type: "immediate",
-				installationId
+				commandVersions: base?.commandVersions,
+				installedAt,
+				guildSnapshot,
+				snapshotAt: now,
+				snapshotApplicationId: app.applicationId,
+				targetGuildId: options.guildId ?? base?.targetGuildId
 			};
-		}
-		const pending = {
-			id: installationId,
-			agentId,
-			webhookId,
-			status: "pending",
-			guildIds: existing?.guildIds ?? [],
-			displayName,
-			commands: commands.length ? commands : void 0,
-			commandVersions: existing?.commandVersions,
-			installedAt
-		};
-		await store.save(pending);
+			await store.save(pending);
+			return pending;
+		});
+		if ("type" in outcome) return outcome;
+		const pending = outcome;
 		await this.#registerCommands(app, pending);
 		this.#configured = true;
 		return {
@@ -779,7 +1020,22 @@ var DiscordProvider = class {
 	* `webhookId` is unknown.
 	*/
 	async activateGuild(webhookId, guildId) {
-		const next = (this.#activationChains.get(webhookId) ?? Promise.resolve()).catch(() => {}).then(() => this.#activateGuildNow(webhookId, guildId));
+		return this.#enqueueWebhookTask(webhookId, () => this.#activateGuildNow(webhookId, guildId));
+	}
+	#activationChains = /* @__PURE__ */ new Map();
+	/**
+	* Serialize every mutation of one webhook's installation row — activations,
+	* pending-row saves, runtime bring-up, disconnects — so each task's read
+	* happens *after* the previous task's save. Without the chain, two
+	* concurrent first-interactions can lose a guildId (both read the same row,
+	* second save overwrites the first) or fire onInstall twice; a connect's
+	* pending save can clobber a row a racing interaction just activated; and a
+	* disconnect can land mid-activation and be resurrected by its post-HTTP
+	* persistence. The chain entry is dropped once the last queued task settles
+	* so keys don't accumulate forever.
+	*/
+	async #enqueueWebhookTask(webhookId, task) {
+		const next = (this.#activationChains.get(webhookId) ?? Promise.resolve()).catch(() => {}).then(task);
 		this.#activationChains.set(webhookId, next);
 		try {
 			return await next;
@@ -787,7 +1043,6 @@ var DiscordProvider = class {
 			if (this.#activationChains.get(webhookId) === next) this.#activationChains.delete(webhookId);
 		}
 	}
-	#activationChains = /* @__PURE__ */ new Map();
 	async #activateGuildNow(webhookId, guildId) {
 		const store = await this.#getStore();
 		const installation = await store.getByWebhookId(webhookId);
@@ -797,6 +1052,10 @@ var DiscordProvider = class {
 		if (wasActive && known) return installation;
 		if (!known) installation.guildIds.push(guildId);
 		installation.status = "active";
+		delete installation.guildSnapshot;
+		delete installation.snapshotAt;
+		delete installation.snapshotApplicationId;
+		delete installation.targetGuildId;
 		await store.save(installation);
 		const app = await store.getAppConfig();
 		if (app) await this.#registerCommands(app, installation, guildId);
@@ -805,26 +1064,106 @@ var DiscordProvider = class {
 		return installation;
 	}
 	/**
-	* Disconnect an agent from Discord: remove its installation row and drop the
-	* adapter entry.
-	*
-	* **Limitation:** the Gateway loop is owned by core (it calls
-	* `startGatewayListener` itself; there is no `stopGatewayListener`), so
-	* disconnect cannot kill an in-flight gateway window — it lapses at the next
-	* duration boundary. Contrast Telegram's clean `stopPolling()`.
+	* Disconnect an agent from Discord: abort its Gateway loop, remove its
+	* installation row, and drop the adapter entry.
 	*/
 	async disconnect(agentId) {
 		const store = await this.#getStore();
 		const existing = await store.getByAgent(agentId);
 		if (!existing) throw new Error(`No Discord installation found for agent "${agentId}"`);
-		this.#adapters.delete(existing.id);
-		await store.deleteByAgent(agentId);
+		await this.#enqueueWebhookTask(existing.webhookId, async () => {
+			this.#stopGatewayLoop(existing.id);
+			this.#adapters.delete(existing.id);
+			await store.deleteByAgent(agentId);
+		});
 		this.#configured = await store.getAppConfig() != null || (await store.list()).some((i) => i.status === "active");
 	}
-	/** List installations (public info only — no secrets). */
+	/**
+	* List installations (public info only — no secrets). A pure read: pending
+	* installs are confirmed through the write-authorized
+	* {@link reconcileInstallation} path, never as a listing side effect.
+	*/
 	async listInstallations() {
 		return (await (await this.#getStore()).list()).map(toInstallationInfo);
 	}
+	/**
+	* Activate an agent's pending install if its invite has since been completed.
+	*
+	* The invite URL carries no `redirect_uri` (the app would have to allowlist
+	* every operator origin), so nothing calls back when the operator authorizes
+	* the bot — and a pending install has no adapter, so no interaction or
+	* gateway event can reach it either. Instead, each pending install carries a
+	* {@link DiscordInstallation.guildSnapshot} taken when the invite was issued;
+	* this diffs it against the bot's current membership and activates the
+	* install when exactly one new, uncontested guild has appeared (the full
+	* claim rules live in {@link planReconcile}). The claim analysis spans every
+	* install — other pending invites contest the diff — but only **this**
+	* agent's install can activate: the caller holds write access for this agent
+	* alone. Anything ambiguous stays pending and retries on the next call, with
+	* the first interaction as the authoritative fallback. Best-effort: failures
+	* log and resolve rather than throw.
+	*
+	* Called by the server's reconcile route (write-authorized); Studio invokes
+	* it on window focus while a connect is in flight. Returns the (possibly
+	* just-activated) installation's public info, or `null` when the agent has
+	* no installation.
+	*
+	* Limitation: the bot-invite URL is per-app, not per-install, so when the
+	* operator invites the bot to a new server *for an already-active install*
+	* (as `connect()`'s already-connected error suggests) while an invite for
+	* another agent is outstanding, nothing distinguishes the two intents — the
+	* new guild can be attributed to the pending install. Reconciliation is only
+	* reliable while a single invite flow is in progress.
+	*/
+	async reconcileInstallation(agentId) {
+		const store = await this.#getStore();
+		const existing = await store.getByAgent(agentId);
+		if (!existing) return null;
+		if (existing.status === "pending") {
+			const inflight = this.#reconcileInflight.get(agentId);
+			if (inflight) await inflight;
+			else {
+				const run = this.#reconcilePendingInstallation(store, agentId).finally(() => {
+					this.#reconcileInflight.delete(agentId);
+				});
+				this.#reconcileInflight.set(agentId, run);
+				await run;
+			}
+		}
+		const fresh = await store.getByAgent(agentId);
+		return fresh ? toInstallationInfo(fresh) : null;
+	}
+	#reconcileInflight = /* @__PURE__ */ new Map();
+	async #reconcilePendingInstallation(store, agentId) {
+		try {
+			const app = await store.getAppConfig();
+			if (!app) return;
+			const target = await store.getByAgent(agentId);
+			if (!target || target.status !== "pending") return;
+			if (!hasReconcilableSnapshot(target, app.applicationId, /* @__PURE__ */ new Date())) return;
+			const current = await listBotGuildIds(app.botToken, this.#apiBaseUrl());
+			if (!current) return;
+			const activation = planReconcile({
+				installations: await store.list(),
+				currentGuildIds: current,
+				applicationId: app.applicationId,
+				now: /* @__PURE__ */ new Date()
+			}).find((a) => a.agentId === agentId);
+			if (!activation) return;
+			await this.#enqueueWebhookTask(activation.webhookId, async () => {
+				const activated = await this.#activateGuildNow(activation.webhookId, activation.guildId);
+				if (!activated || this.#adapters.has(activated.id)) return;
+				try {
+					await this.#activateInstallation(activated);
+				} catch (err) {
+					this.#adapters.delete(activated.id);
+					throw err;
+				}
+			});
+		} catch (err) {
+			console.warn(`[Discord] Pending-install reconcile for agent "${agentId}" failed (will retry):`, err);
+		}
+	}
 	/** The full installation for an agent (no secrets live on it), or `null`. */
 	async getInstallation(agentId) {
 		return await (await this.#getStore()).getByAgent(agentId) ?? null;
@@ -867,6 +1206,7 @@ var DiscordProvider = class {
 		if (!channels || channels.adapters["discord"] !== adapter) {
 			channels = this.#createAgentChannels(agent, adapter);
 			await channels.initialize(this.#mastra);
+			this.#startGatewayLoop(installation, adapter, app);
 		}
 		try {
 			return scheduleActivation(await channels.handleWebhookEvent(PLATFORM, c.req.raw, waitUntil ? { waitUntil } : void 0));
@@ -908,7 +1248,14 @@ var DiscordProvider = class {
 				...versions,
 				[key]: hash
 			};
-			await (await this.#getStore()).save(installation);
+			const store = await this.#getStore();
+			const fresh = await store.getByWebhookId(installation.webhookId);
+			if (!fresh) return;
+			fresh.commandVersions = {
+				...fresh.commandVersions,
+				[key]: hash
+			};
+			await store.save(fresh);
 		} catch (err) {
 			console.warn(`[Discord] command registration failed (${scope}${guildId ? `, guild ${guildId}` : ""}):`, err);
 		}
@@ -936,13 +1283,64 @@ var DiscordProvider = class {
 		if (!app) return;
 		const agent = this.#resolveAgent(installation.agentId);
 		const adapter = this.#getOrCreateAdapter(installation, app);
-		if (agent && this.#mastra) await this.#createAgentChannels(agent, adapter).initialize(this.#mastra);
+		if (agent && this.#mastra) {
+			await this.#createAgentChannels(agent, adapter).initialize(this.#mastra);
+			this.#startGatewayLoop(installation, adapter, app);
+		}
+	}
+	/**
+	* Start (or restart) the Gateway reconnect loop for an installation. Any
+	* previous loop for the same installation is aborted first, so adapter
+	* rebuilds and credential rotations replace the loop instead of stacking
+	* another one. No-op when the provider is configured `gateway: false`.
+	*
+	* The loop itself lives in {@link runGatewayLoop}; see that module for why
+	* the provider owns this instead of core's `AgentChannels` loop.
+	*/
+	#startGatewayLoop(installation, adapter, app) {
+		if (!resolveDiscordAdapterConfig(this.#config).gateway) return;
+		this.#stopGatewayLoop(installation.id);
+		const controller = new AbortController();
+		this.#gatewayLoops.set(installation.id, controller);
+		const apiBaseUrl = this.#apiBaseUrl();
+		runGatewayLoop({
+			startSession: (options, durationMs, signal) => adapter.startGatewayListener(options, durationMs, signal),
+			checkToken: async () => {
+				try {
+					const response = await discordRequest(app.botToken, "GET", "/applications/@me", apiBaseUrl);
+					return response.status === 401 ? "invalid" : response.ok ? "valid" : "unreachable";
+				} catch {
+					return "unreachable";
+				}
+			},
+			log: (level, message) => {
+				const line = `[Discord] [gateway:${installation.agentId}] ${message}`;
+				if (level === "error") console.error(line);
+				else if (level === "warn") console.warn(line);
+				else console.info(line);
+			}
+		}, controller.signal).finally(() => {
+			if (this.#gatewayLoops.get(installation.id) === controller) this.#gatewayLoops.delete(installation.id);
+		});
+	}
+	/** Abort an installation's Gateway loop (ends the session, destroys the client). */
+	#stopGatewayLoop(installationId) {
+		const controller = this.#gatewayLoops.get(installationId);
+		if (!controller) return;
+		this.#gatewayLoops.delete(installationId);
+		controller.abort();
+	}
+	/** Abort every Gateway loop — credential revocation or Mastra re-attach. */
+	#stopAllGatewayLoops() {
+		for (const installationId of [...this.#gatewayLoops.keys()]) this.#stopGatewayLoop(installationId);
 	}
 	/**
 	* Create AgentChannels for an agent with the Discord adapter, preserving any
 	* adapters/config the agent author already configured (mirrors `@mastra/slack`
-	* / `@mastra/telegram`). `gateway: true` (default) makes core start the Gateway
-	* reconnection loop for DMs/mentions.
+	* / `@mastra/telegram`). The entry always carries `gateway: false`: core's
+	* built-in gateway loop reconnects with no backoff and no abort handle, so
+	* the provider owns the Gateway lifecycle instead ({@link #startGatewayLoop},
+	* gated on the provider-level `gateway` config).
 	*/
 	#createAgentChannels(agent, adapter) {
 		const existingConfig = agent.getChannels()?.channelConfig;
@@ -950,6 +1348,7 @@ var DiscordProvider = class {
 		const entry = {
 			adapter,
 			...resolveDiscordAdapterConfig(cfg),
+			gateway: false,
 			...cfg.cors !== void 0 ? { cors: cfg.cors } : {},
 			...cfg.formatError !== void 0 ? { formatError: cfg.formatError } : {}
 		};