@alfe.ai/agent-api-client 0.1.4 → 0.2.1

package/dist/index.cjs

@@ -7,6 +7,25 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 function encodeFilePath(filePath) {
 	return filePath.split("/").map(encodeURIComponent).join("/");
 }
+const REQUEST_TIMEOUT_MS = 2e4;
+const RETRYABLE_STATUS = new Set([
+	500,
+	502,
+	503,
+	504
+]);
+const RETRY_DELAY_MS = 500;
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+function isRetryableNetworkError(err) {
+	if (!(err instanceof Error)) return false;
+	if (err.name === "TimeoutError" || err.name === "AbortError") return true;
+	if (err.name === "TypeError") return true;
+	return false;
+}
 var AgentApiClient = class {
 	apiKey;
 	apiUrl;
@@ -19,15 +38,33 @@ var AgentApiClient = class {
 		const headers = new Headers(options?.headers);
 		headers.set("Authorization", `Bearer ${this.apiKey}`);
 		headers.set("Content-Type", "application/json");
-		const res = await fetch(url, {
-			...options,
-			headers
-		});
-		if (!res.ok) {
-			await res.text();
-			throw new Error(`Agent API request failed (${String(res.status)})`);
+		let lastError;
+		for (let attempt = 1; attempt <= 2; attempt++) try {
+			const res = await fetch(url, {
+				...options,
+				headers,
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+			});
+			if (!res.ok) {
+				await res.text();
+				const error = /* @__PURE__ */ new Error(`Agent API request failed (${String(res.status)})`);
+				if (attempt === 1 && RETRYABLE_STATUS.has(res.status)) {
+					lastError = error;
+					await sleep(RETRY_DELAY_MS);
+					continue;
+				}
+				throw error;
+			}
+			return (await res.json()).data;
+		} catch (err) {
+			if (attempt === 1 && isRetryableNetworkError(err)) {
+				lastError = err;
+				await sleep(RETRY_DELAY_MS);
+				continue;
+			}
+			throw err;
 		}
-		return (await res.json()).data;
+		throw lastError instanceof Error ? lastError : new Error(String(lastError));
 	}
 	async syncRegister(args) {
 		return this.request("/agent/sync/register", {
@@ -146,6 +183,14 @@ var AgentApiClient = class {
 	async getGoogleChatCredentials() {
 		return this.request("/agent/google-chat/credentials");
 	}
+	/**
+	* @deprecated Returns a single primary credential blob (legacy "pick-the-
+	* default-connection" shape). Use `getGithubAccounts()` for the multi-
+	* account shape required by Pattern A — explicit selector args on every
+	* tool. Retained because the `@alfe.ai/openclaw-github` proxy is the
+	* only consumer that knows about Pattern A; legacy env-interpolation
+	* callers will keep hitting `/credentials` until they move to the proxy.
+	*/
 	async getGithubCredentials() {
 		const raw = await this.request("/agent/connect/github/credentials");
 		return {
@@ -153,6 +198,37 @@ var AgentApiClient = class {
 			accessToken: raw.accessToken
 		};
 	}
+	/**
+	* Pattern A: multi-account credential fetch for GitHub.
+	*
+	* Returns every agent-scoped GitHub connection. The caller is expected
+	* to require a `login` selector on every credential-touching tool and
+	* look up the matching account at dispatch time.
+	*
+	* GitHub OAuth tokens have no expiry (`tokenLifecycle: "no_expiry"`),
+	* so there is intentionally no `refreshGithubAccountToken` method — if
+	* a token is revoked the user must re-run the OAuth flow.
+	*
+	* Returned `accounts[i].login` is the GitHub username — the stable
+	* cross-session identifier the LLM should pass.
+	*/
+	async getGithubAccounts() {
+		return { accounts: (await this.request("/agent/connect/github/accounts")).accounts.map((a) => ({
+			connectionId: a.connectionId,
+			accountIdentifier: a.accountIdentifier,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			accessToken: a.accessToken ?? "",
+			login: a.login ?? a.accountIdentifier,
+			scopes: a.scopes ?? ""
+		})) };
+	}
+	/**
+	* @deprecated Returns a single primary credential blob (legacy "pick-the-
+	* default-connection" shape). Use `getXeroAccounts()` for the multi-
+	* account shape required by Pattern A — explicit selector args on every
+	* tool. This method will be removed once all consumers migrate.
+	*/
 	async getXeroCredentials() {
 		const raw = await this.request("/agent/connect/xero/credentials");
 		return {
@@ -161,9 +237,49 @@ var AgentApiClient = class {
 			xeroTenantId: raw.xeroTenantId ?? ""
 		};
 	}
+	/**
+	* Pattern A: multi-account credential fetch for Xero. Returns every
+	* agent-scoped Xero connection. The caller is expected to require a
+	* selector arg (e.g. `xeroTenantId`) on every credential-touching tool
+	* and look up the matching account by that selector at dispatch time.
+	*
+	* Returned `accounts[i].accountIdentifier` is the Xero tenantId — the
+	* stable cross-session identifier the LLM should pass.
+	*/
+	async getXeroAccounts() {
+		return { accounts: (await this.request("/agent/connect/xero/accounts")).accounts.map((a) => ({
+			connectionId: a.connectionId,
+			accountIdentifier: a.accountIdentifier,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			accessToken: a.accessToken,
+			accessTokenExpiresAt: a.accessTokenExpiresAt ?? "",
+			xeroTenantId: a.xeroTenantId ?? a.accountIdentifier
+		})) };
+	}
 	async refreshXeroToken() {
 		return this.request("/agent/connect/xero/refresh", { method: "POST" });
 	}
+	/**
+	* Pattern A: refresh a specific Xero connection by its `accountIdentifier`
+	* (the Xero `tenantId`). The legacy `refreshXeroToken()` only refreshes
+	* the *primary* connection, which is wrong for multi-tenant Xero where
+	* each tenant has its own non-interchangeable access token.
+	*/
+	async refreshXeroAccountToken(xeroTenantId) {
+		const path = `/agent/connect/xero/accounts/${encodeURIComponent(xeroTenantId)}/refresh`;
+		const raw = await this.request(path, { method: "POST" });
+		return {
+			accessToken: raw.accessToken,
+			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
+			expiresAt: raw.expiresAt ?? ""
+		};
+	}
+	/**
+	* @deprecated Returns a single primary credential blob (legacy "pick-the-
+	* default-connection" shape). Use `getNotionAccounts()` for the multi-
+	* account shape required by Pattern A.
+	*/
 	async getNotionCredentials() {
 		const raw = await this.request("/agent/connect/notion/credentials");
 		return {
@@ -172,6 +288,32 @@ var AgentApiClient = class {
 			workspaceName: raw.workspaceName ?? ""
 		};
 	}
+	/**
+	* Pattern A: multi-account credential fetch for Notion. Returns every
+	* agent-scoped Notion connection. The caller is expected to require a
+	* selector arg (e.g. `workspaceId`) on every credential-touching tool.
+	*
+	* Returned `accounts[i].accountIdentifier` is the Notion workspaceId.
+	*/
+	async getNotionAccounts() {
+		return { accounts: (await this.request("/agent/connect/notion/accounts")).accounts.map((a) => ({
+			connectionId: a.connectionId,
+			accountIdentifier: a.accountIdentifier,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			accessToken: a.accessToken,
+			workspaceId: a.workspaceId ?? a.accountIdentifier,
+			workspaceName: a.workspaceName ?? a.displayName ?? ""
+		})) };
+	}
+	/**
+	* @deprecated Returns a single primary Atlassian Connection's credentials
+	* (one OAuth user, one cloudId) — the legacy "pick-the-default-connection"
+	* shape. Atlassian is multi-site by nature (each OAuth user may have
+	* access to multiple Cloud sites), so Pattern A plugins MUST use
+	* `getAtlassianAccounts()` to discover the full set and dispatch via
+	* the `cloudId` selector arg.
+	*/
 	async getAtlassianCredentials() {
 		const raw = await this.request("/agent/connect/atlassian/credentials");
 		return {
@@ -190,6 +332,72 @@ var AgentApiClient = class {
 	async refreshAtlassianToken() {
 		return this.request("/agent/connect/atlassian/refresh", { method: "POST" });
 	}
+	/**
+	* Pattern A: multi-account / multi-site credential fetch for Atlassian.
+	*
+	* Returns every agent-scoped Atlassian Connection. Each Connection is
+	* one OAuth user with a single access token and N accessible Cloud
+	* sites (`availableSites`). The caller is expected to:
+	*
+	*   1. Flatten (connection × cloudId) into one MCP child per site.
+	*   2. Require a `cloudId` selector on every credential-touching tool.
+	*   3. Use the access token bound to the Connection that owns the
+	*      requested `cloudId` (Atlassian shares one access token across
+	*      all sites accessible to the OAuth user).
+	*
+	* Per-account token refresh uses `refreshAtlassianAccountToken(email)`
+	* — refreshing one Connection rotates its single access token, which
+	* then applies to every cloudId for that Connection.
+	*
+	* Returned `accounts[i].accountIdentifier` is the OAuth user's email
+	* — the stable cross-session identifier for refresh purposes. The LLM
+	* never sees this directly: it picks a site via the `cloudId` arg
+	* instead.
+	*/
+	async getAtlassianAccounts() {
+		return { accounts: (await this.request("/agent/connect/atlassian/accounts")).accounts.map((a) => ({
+			connectionId: a.connectionId,
+			accountIdentifier: a.accountIdentifier,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			accessToken: a.accessToken ?? "",
+			accessTokenExpiresAt: a.accessTokenExpiresAt ?? "",
+			clientId: a.clientId ?? "",
+			clientSecret: a.clientSecret ?? "",
+			cloudId: a.cloudId ?? "",
+			siteName: a.siteName ?? "",
+			siteUrl: a.siteUrl ?? "",
+			availableSites: a.availableSites ?? []
+		})) };
+	}
+	/**
+	* Pattern A: refresh a specific Atlassian Connection by `accountIdentifier`
+	* (the OAuth user's email).
+	*
+	* Atlassian rotates refresh tokens (`rotatesRefreshToken: true`); the
+	* server-side per-account refresh endpoint handles rotation and
+	* persistence. Refreshing one Connection updates its single access
+	* token, which applies to every accessible Cloud site (cloudId) for
+	* that OAuth user.
+	*
+	* Returns the new access token + expiry. The proxy is responsible for
+	* fanning the new token out to every child server it spawned for
+	* cloudIds owned by this Connection.
+	*/
+	async refreshAtlassianAccountToken(accountIdentifier) {
+		const path = `/agent/connect/atlassian/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
+		const raw = await this.request(path, { method: "POST" });
+		return {
+			accessToken: raw.accessToken,
+			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
+			expiresAt: raw.expiresAt ?? ""
+		};
+	}
+	/**
+	* @deprecated Returns a single primary credential blob (legacy "pick-the-
+	* default-connection" shape). Use `getMYOBAccounts()` for the multi-
+	* account shape required by Pattern A.
+	*/
 	async getMYOBCredentials() {
 		const raw = await this.request("/agent/connect/myob/credentials");
 		return {
@@ -199,9 +407,109 @@ var AgentApiClient = class {
 			clientId: raw.clientId
 		};
 	}
+	/**
+	* Pattern A: multi-account credential fetch for MYOB. Returns every
+	* agent-scoped MYOB connection. The caller is expected to require a
+	* selector arg (e.g. `myobBusinessId` / `accountIdentifier`) on every
+	* credential-touching tool.
+	*
+	* Returned `accounts[i].accountIdentifier` is the MYOB businessId.
+	*/
+	async getMYOBAccounts() {
+		return { accounts: (await this.request("/agent/connect/myob/accounts")).accounts.map((a) => ({
+			connectionId: a.connectionId,
+			accountIdentifier: a.accountIdentifier,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			accessToken: a.accessToken,
+			accessTokenExpiresAt: a.accessTokenExpiresAt ?? "",
+			myobBusinessId: a.myobBusinessId ?? a.accountIdentifier,
+			clientId: a.clientId
+		})) };
+	}
 	async refreshMYOBToken() {
 		return this.request("/agent/connect/myob/refresh", { method: "POST" });
 	}
+	/**
+	* Microsoft 365 (delegated OAuth) credential fetch — single-account shape.
+	*
+	* @deprecated Use `getMicrosoftAccounts()` and dispatch via the `email`
+	*   selector once per-account plugins land. Retained because the existing
+	*   `integrations/connect/microsoft/hooks/post_activate.mjs` writes
+	*   `mgc` credentials for the single (default) Microsoft account.
+	*
+	* Returns the agent's effective Microsoft delegated-OAuth credentials.
+	* Distinct from `getTeamsCredentials()` (Azure bot credentials for the
+	* Teams adapter, which is admin-consent flow on services/microsoft, not
+	* delegated OAuth on services/connect).
+	*/
+	async getMicrosoftCredentials() {
+		const raw = await this.request("/agent/connect/microsoft/credentials");
+		return {
+			accessToken: raw.accessToken ?? "",
+			accessTokenExpiresAt: raw.accessTokenExpiresAt,
+			refreshToken: raw.refreshToken ?? "",
+			clientId: raw.clientId ?? "",
+			clientSecret: raw.clientSecret ?? "",
+			email: raw.email ?? raw.accountIdentifier,
+			microsoftTenantId: raw.microsoftTenantId,
+			workspaceDomain: raw.workspaceDomain
+		};
+	}
+	/**
+	* Pattern A: multi-account credential fetch for Microsoft 365.
+	*
+	* Returns every agent-scoped Microsoft connection. The caller is expected
+	* to require an `email` selector on every credential-touching tool and
+	* look up the matching account at dispatch time.
+	*
+	* Returned `accounts[i].accountIdentifier` is the user's primary email
+	* (or the tid claim as fallback) — the stable cross-session identifier
+	* the LLM should pass.
+	*
+	* Per-account token refresh is exposed via `refreshMicrosoftAccountToken`,
+	* NOT `refreshXeroAccountToken` — Microsoft refresh tokens are not
+	* interchangeable across (tenant, user) pairs.
+	*/
+	async getMicrosoftAccounts() {
+		return { accounts: (await this.request("/agent/connect/microsoft/accounts")).accounts.map((a) => ({
+			connectionId: a.connectionId,
+			accountIdentifier: a.accountIdentifier,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			accessToken: a.accessToken ?? "",
+			accessTokenExpiresAt: a.accessTokenExpiresAt ?? "",
+			refreshToken: a.refreshToken ?? "",
+			clientId: a.clientId ?? "",
+			clientSecret: a.clientSecret ?? "",
+			email: a.email ?? a.accountIdentifier,
+			microsoftTenantId: a.microsoftTenantId ?? "",
+			workspaceDomain: a.workspaceDomain ?? ""
+		})) };
+	}
+	/**
+	* Pattern A: refresh a specific Microsoft 365 connection by its
+	* `accountIdentifier`. For Microsoft, `accountIdentifier` is the user's
+	* email when the Graph profile fetch succeeded at connect time, and the
+	* Azure tenant id (`tid` claim) as fallback. Callers should pass the
+	* value returned by `getMicrosoftAccounts()` rather than synthesising
+	* an email locally.
+	*
+	* Microsoft refresh tokens are bound to a specific (tenant, user) pair —
+	* they are NOT interchangeable across accounts, so per-account refresh
+	* is mandatory. The generic /accounts/{accountIdentifier}/refresh
+	* endpoint walks the agent's full visible scope chain to find a matching
+	* connection (works for inherited team/project Microsoft connections).
+	*/
+	async refreshMicrosoftAccountToken(accountIdentifier) {
+		const path = `/agent/connect/microsoft/accounts/${encodeURIComponent(accountIdentifier)}/refresh`;
+		const raw = await this.request(path, { method: "POST" });
+		return {
+			accessToken: raw.accessToken,
+			accessTokenExpiresAt: raw.accessTokenExpiresAt ?? "",
+			expiresAt: raw.expiresAt ?? ""
+		};
+	}
 	async getTeamsCredentials() {
 		return this.request("/agent/microsoft/credentials");
 	}

package/dist/index.d.cts

@@ -202,24 +202,125 @@ declare class AgentApiClient {
     clientSecret: string;
     displayName?: string;
   }>;
+  /**
+   * @deprecated Returns a single primary credential blob (legacy "pick-the-
+   * default-connection" shape). Use `getGithubAccounts()` for the multi-
+   * account shape required by Pattern A — explicit selector args on every
+   * tool. Retained because the `@alfe.ai/openclaw-github` proxy is the
+   * only consumer that knows about Pattern A; legacy env-interpolation
+   * callers will keep hitting `/credentials` until they move to the proxy.
+   */
   getGithubCredentials(): Promise<{
     login: string;
     accessToken: string;
   }>;
+  /**
+   * Pattern A: multi-account credential fetch for GitHub.
+   *
+   * Returns every agent-scoped GitHub connection. The caller is expected
+   * to require a `login` selector on every credential-touching tool and
+   * look up the matching account at dispatch time.
+   *
+   * GitHub OAuth tokens have no expiry (`tokenLifecycle: "no_expiry"`),
+   * so there is intentionally no `refreshGithubAccountToken` method — if
+   * a token is revoked the user must re-run the OAuth flow.
+   *
+   * Returned `accounts[i].login` is the GitHub username — the stable
+   * cross-session identifier the LLM should pass.
+   */
+  getGithubAccounts(): Promise<{
+    accounts: {
+      connectionId: string;
+      accountIdentifier: string;
+      displayName: string | null;
+      connectedAt: string;
+      accessToken: string;
+      login: string;
+      scopes: string;
+    }[];
+  }>;
+  /**
+   * @deprecated Returns a single primary credential blob (legacy "pick-the-
+   * default-connection" shape). Use `getXeroAccounts()` for the multi-
+   * account shape required by Pattern A — explicit selector args on every
+   * tool. This method will be removed once all consumers migrate.
+   */
   getXeroCredentials(): Promise<{
     accessToken: string;
     accessTokenExpiresAt: string;
     xeroTenantId: string;
   }>;
+  /**
+   * Pattern A: multi-account credential fetch for Xero. Returns every
+   * agent-scoped Xero connection. The caller is expected to require a
+   * selector arg (e.g. `xeroTenantId`) on every credential-touching tool
+   * and look up the matching account by that selector at dispatch time.
+   *
+   * Returned `accounts[i].accountIdentifier` is the Xero tenantId — the
+   * stable cross-session identifier the LLM should pass.
+   */
+  getXeroAccounts(): Promise<{
+    accounts: {
+      connectionId: string;
+      accountIdentifier: string;
+      displayName: string | null;
+      connectedAt: string;
+      accessToken: string;
+      accessTokenExpiresAt: string;
+      xeroTenantId: string;
+    }[];
+  }>;
   refreshXeroToken(): Promise<{
     accessToken: string;
     expiresAt: string;
   }>;
+  /**
+   * Pattern A: refresh a specific Xero connection by its `accountIdentifier`
+   * (the Xero `tenantId`). The legacy `refreshXeroToken()` only refreshes
+   * the *primary* connection, which is wrong for multi-tenant Xero where
+   * each tenant has its own non-interchangeable access token.
+   */
+  refreshXeroAccountToken(xeroTenantId: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
+  /**
+   * @deprecated Returns a single primary credential blob (legacy "pick-the-
+   * default-connection" shape). Use `getNotionAccounts()` for the multi-
+   * account shape required by Pattern A.
+   */
   getNotionCredentials(): Promise<{
     accessToken: string;
     workspaceId: string;
     workspaceName: string;
   }>;
+  /**
+   * Pattern A: multi-account credential fetch for Notion. Returns every
+   * agent-scoped Notion connection. The caller is expected to require a
+   * selector arg (e.g. `workspaceId`) on every credential-touching tool.
+   *
+   * Returned `accounts[i].accountIdentifier` is the Notion workspaceId.
+   */
+  getNotionAccounts(): Promise<{
+    accounts: {
+      connectionId: string;
+      accountIdentifier: string;
+      displayName: string | null;
+      connectedAt: string;
+      accessToken: string;
+      workspaceId: string;
+      workspaceName: string;
+    }[];
+  }>;
+  /**
+   * @deprecated Returns a single primary Atlassian Connection's credentials
+   * (one OAuth user, one cloudId) — the legacy "pick-the-default-connection"
+   * shape. Atlassian is multi-site by nature (each OAuth user may have
+   * access to multiple Cloud sites), so Pattern A plugins MUST use
+   * `getAtlassianAccounts()` to discover the full set and dispatch via
+   * the `cloudId` selector arg.
+   */
   getAtlassianCredentials(): Promise<{
     accessToken: string;
     refreshToken: string;
@@ -236,16 +337,177 @@ declare class AgentApiClient {
     accessToken: string;
     expiresAt: string;
   }>;
+  /**
+   * Pattern A: multi-account / multi-site credential fetch for Atlassian.
+   *
+   * Returns every agent-scoped Atlassian Connection. Each Connection is
+   * one OAuth user with a single access token and N accessible Cloud
+   * sites (`availableSites`). The caller is expected to:
+   *
+   *   1. Flatten (connection × cloudId) into one MCP child per site.
+   *   2. Require a `cloudId` selector on every credential-touching tool.
+   *   3. Use the access token bound to the Connection that owns the
+   *      requested `cloudId` (Atlassian shares one access token across
+   *      all sites accessible to the OAuth user).
+   *
+   * Per-account token refresh uses `refreshAtlassianAccountToken(email)`
+   * — refreshing one Connection rotates its single access token, which
+   * then applies to every cloudId for that Connection.
+   *
+   * Returned `accounts[i].accountIdentifier` is the OAuth user's email
+   * — the stable cross-session identifier for refresh purposes. The LLM
+   * never sees this directly: it picks a site via the `cloudId` arg
+   * instead.
+   */
+  getAtlassianAccounts(): Promise<{
+    accounts: {
+      connectionId: string;
+      accountIdentifier: string;
+      displayName: string | null;
+      connectedAt: string;
+      accessToken: string;
+      accessTokenExpiresAt: string;
+      clientId: string;
+      clientSecret: string;
+      cloudId: string;
+      siteName: string;
+      siteUrl: string;
+      availableSites: {
+        id: string;
+        url: string;
+        name: string;
+        scopes?: string[];
+        avatarUrl?: string;
+      }[];
+    }[];
+  }>;
+  /**
+   * Pattern A: refresh a specific Atlassian Connection by `accountIdentifier`
+   * (the OAuth user's email).
+   *
+   * Atlassian rotates refresh tokens (`rotatesRefreshToken: true`); the
+   * server-side per-account refresh endpoint handles rotation and
+   * persistence. Refreshing one Connection updates its single access
+   * token, which applies to every accessible Cloud site (cloudId) for
+   * that OAuth user.
+   *
+   * Returns the new access token + expiry. The proxy is responsible for
+   * fanning the new token out to every child server it spawned for
+   * cloudIds owned by this Connection.
+   */
+  refreshAtlassianAccountToken(accountIdentifier: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
+  /**
+   * @deprecated Returns a single primary credential blob (legacy "pick-the-
+   * default-connection" shape). Use `getMYOBAccounts()` for the multi-
+   * account shape required by Pattern A.
+   */
   getMYOBCredentials(): Promise<{
     accessToken: string;
     accessTokenExpiresAt: string;
     myobBusinessId: string;
     clientId: string;
   }>;
+  /**
+   * Pattern A: multi-account credential fetch for MYOB. Returns every
+   * agent-scoped MYOB connection. The caller is expected to require a
+   * selector arg (e.g. `myobBusinessId` / `accountIdentifier`) on every
+   * credential-touching tool.
+   *
+   * Returned `accounts[i].accountIdentifier` is the MYOB businessId.
+   */
+  getMYOBAccounts(): Promise<{
+    accounts: {
+      connectionId: string;
+      accountIdentifier: string;
+      displayName: string | null;
+      connectedAt: string;
+      accessToken: string;
+      accessTokenExpiresAt: string;
+      myobBusinessId: string;
+      clientId: string;
+    }[];
+  }>;
   refreshMYOBToken(): Promise<{
     accessToken: string;
     expiresAt: string;
   }>;
+  /**
+   * Microsoft 365 (delegated OAuth) credential fetch — single-account shape.
+   *
+   * @deprecated Use `getMicrosoftAccounts()` and dispatch via the `email`
+   *   selector once per-account plugins land. Retained because the existing
+   *   `integrations/connect/microsoft/hooks/post_activate.mjs` writes
+   *   `mgc` credentials for the single (default) Microsoft account.
+   *
+   * Returns the agent's effective Microsoft delegated-OAuth credentials.
+   * Distinct from `getTeamsCredentials()` (Azure bot credentials for the
+   * Teams adapter, which is admin-consent flow on services/microsoft, not
+   * delegated OAuth on services/connect).
+   */
+  getMicrosoftCredentials(): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt?: string;
+    refreshToken: string;
+    clientId: string;
+    clientSecret: string;
+    email?: string;
+    microsoftTenantId?: string;
+    workspaceDomain?: string;
+  }>;
+  /**
+   * Pattern A: multi-account credential fetch for Microsoft 365.
+   *
+   * Returns every agent-scoped Microsoft connection. The caller is expected
+   * to require an `email` selector on every credential-touching tool and
+   * look up the matching account at dispatch time.
+   *
+   * Returned `accounts[i].accountIdentifier` is the user's primary email
+   * (or the tid claim as fallback) — the stable cross-session identifier
+   * the LLM should pass.
+   *
+   * Per-account token refresh is exposed via `refreshMicrosoftAccountToken`,
+   * NOT `refreshXeroAccountToken` — Microsoft refresh tokens are not
+   * interchangeable across (tenant, user) pairs.
+   */
+  getMicrosoftAccounts(): Promise<{
+    accounts: {
+      connectionId: string;
+      accountIdentifier: string;
+      displayName: string | null;
+      connectedAt: string;
+      accessToken: string;
+      accessTokenExpiresAt: string;
+      refreshToken: string;
+      clientId: string;
+      clientSecret: string;
+      email: string;
+      microsoftTenantId: string;
+      workspaceDomain: string;
+    }[];
+  }>;
+  /**
+   * Pattern A: refresh a specific Microsoft 365 connection by its
+   * `accountIdentifier`. For Microsoft, `accountIdentifier` is the user's
+   * email when the Graph profile fetch succeeded at connect time, and the
+   * Azure tenant id (`tid` claim) as fallback. Callers should pass the
+   * value returned by `getMicrosoftAccounts()` rather than synthesising
+   * an email locally.
+   *
+   * Microsoft refresh tokens are bound to a specific (tenant, user) pair —
+   * they are NOT interchangeable across accounts, so per-account refresh
+   * is mandatory. The generic /accounts/{accountIdentifier}/refresh
+   * endpoint walks the agent's full visible scope chain to find a matching
+   * connection (works for inherited team/project Microsoft connections).
+   */
+  refreshMicrosoftAccountToken(accountIdentifier: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
   getTeamsCredentials(): Promise<{
     agentId: string;
     tenantId: string;