mastra-ai
diff --git a/‎.changeset/frank-zebras-learn.md‎
Lines changed: 41 additions & 0 deletions b/‎.changeset/frank-zebras-learn.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎packages/core/src/storage/base.ts‎
Lines changed: 5 additions & 0 deletions b/‎packages/core/src/storage/base.ts‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎packages/core/src/storage/constants.ts‎
Lines changed: 30 additions & 1 deletion b/‎packages/core/src/storage/constants.ts‎
Lines changed: 30 additions & 1 deletion
diff --git a/‎packages/core/src/storage/domains/agents/filesystem.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/core/src/storage/domains/agents/filesystem.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/core/src/storage/domains/index.ts‎
Lines changed: 1 addition & 1 deletion b/‎packages/core/src/storage/domains/index.ts‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎packages/core/src/storage/domains/inmemory-db.ts‎
Lines changed: 7 additions & 0 deletions b/‎packages/core/src/storage/domains/inmemory-db.ts‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎packages/core/src/storage/domains/operations/inmemory.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/core/src/storage/domains/operations/inmemory.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/core/src/storage/domains/tool-provider-connections/base.ts‎
Lines changed: 63 additions & 0 deletions b/‎packages/core/src/storage/domains/tool-provider-connections/base.ts‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎packages/core/src/storage/domains/tool-provider-connections/index.ts‎
Lines changed: 2 additions & 0 deletions b/‎packages/core/src/storage/domains/tool-provider-connections/index.ts‎
Lines changed: 2 additions & 0 deletions
@@ -0,0 +1,41 @@
+---
+'@mastra/core': minor
+'@mastra/libsql': minor
+'@mastra/clickhouse': patch
+'@mastra/cloudflare': patch
+---
+
+Added the `tool_provider_connections` storage domain. Stored agents can now persist per-agent ToolProvider config that round-trips on read/write/create. Runtime connection resolution (per-author, shared, caller-supplied) ships in a follow-up PR.
+
+**What you can do**
+
+- Pin a connection on a stored agent's config and have it round-trip on read/write/create.
+- Persist multiple connections per toolkit so a follow-up runtime PR can fan-out to the right one at execution time.
+
+**Example**
+
+```ts
+import { LibSQLStore } from '@mastra/libsql';
+
+const storage = new LibSQLStore({ url: process.env.DATABASE_URL });
+
+// Persist an OAuth connection that an agent can pin later
+await storage.toolProviders.upsertConnection({
+  authorId: 'user-123',
+  providerId: 'composio',
+  connectionId: 'auth_abc',
+  toolkit: 'gmail',
+  label: 'Work inbox',
+  scope: 'per-author',
+});
+
+// List a user's own connections (admin can omit authorId to list across users)
+const { items } = await storage.toolProviders.listConnectionsByAuthor({
+  authorId: 'user-123',
+  providerId: 'composio',
+});
+```
+
+Additive — existing stored agents continue to work unchanged. The runtime that consumes this domain ships in a follow-up PR.
+
+PR 1 of 3 split from #17224.
@@ -19,6 +19,7 @@ import type {
   BackgroundTasksStorage,
   SchedulesStorage,
   ChannelsStorage,
+  ToolProviderConnectionsStorage,
 } from './domains';
 
 /** Map of all storage domain interfaces available in a composite store. */
@@ -41,6 +42,7 @@ export type StorageDomains = {
   blobs?: BlobStore;
   backgroundTasks?: BackgroundTasksStorage;
   schedules?: SchedulesStorage;
+  toolProviderConnections?: ToolProviderConnectionsStorage;
 };
 
 /**
@@ -57,6 +59,7 @@ export const EDITOR_DOMAINS = [
   'workspaces',
   'skills',
   'favorites',
+  'toolProviderConnections',
 ] as const satisfies ReadonlyArray<keyof StorageDomains>;
 
 /**
@@ -324,6 +327,7 @@ export class MastraCompositeStore extends MastraBase {
         backgroundTasks: resolve('backgroundTasks'),
         schedules: resolve('schedules'),
         channels: resolve('channels'),
+        toolProviderConnections: resolve('toolProviderConnections'),
       } as StorageDomains;
     }
     // Otherwise, subclasses set stores themselves
@@ -450,6 +454,7 @@ export class MastraCompositeStore extends MastraBase {
       maybeInit(this.stores.backgroundTasks);
       maybeInit(this.stores.schedules);
       maybeInit(this.stores.channels);
+      maybeInit(this.stores.toolProviderConnections);
     }
 
     await Promise.all(initTasks);
 
@@ -45,6 +45,9 @@ export const TABLE_SCHEDULE_TRIGGERS = 'mastra_schedule_triggers';
 export const TABLE_CHANNEL_INSTALLATIONS = 'mastra_channel_installations';
 export const TABLE_CHANNEL_CONFIG = 'mastra_channel_config';
 
+// Tool provider connections
+export const TABLE_TOOL_PROVIDER_CONNECTIONS = 'mastra_tool_provider_connections';
+
 /** Union of all core table name constants. */
 export type TABLE_NAMES =
   | typeof TABLE_WORKFLOW_SNAPSHOT
@@ -79,7 +82,8 @@ export type TABLE_NAMES =
   | typeof TABLE_SCHEDULES
   | typeof TABLE_SCHEDULE_TRIGGERS
   | typeof TABLE_CHANNEL_INSTALLATIONS
-  | typeof TABLE_CHANNEL_CONFIG;
+  | typeof TABLE_CHANNEL_CONFIG
+  | typeof TABLE_TOOL_PROVIDER_CONNECTIONS;
 
 export const SCORERS_SCHEMA: Record<string, StorageColumn> = {
   id: { type: 'text', nullable: false, primaryKey: true },
@@ -172,6 +176,7 @@ export const AGENT_VERSIONS_SCHEMA: Record<string, StorageColumn> = {
   workflows: { type: 'jsonb', nullable: true },
   agents: { type: 'jsonb', nullable: true },
   integrationTools: { type: 'jsonb', nullable: true },
+  toolProviders: { type: 'jsonb', nullable: true },
   inputProcessors: { type: 'jsonb', nullable: true },
   outputProcessors: { type: 'jsonb', nullable: true },
   memory: { type: 'jsonb', nullable: true },
@@ -338,6 +343,25 @@ export const FAVORITES_SCHEMA: Record<string, StorageColumn> = {
   createdAt: { type: 'timestamp', nullable: false },
 };
 
+/**
+ * Per-author registry of authorized tool provider connections. Stores a stable
+ * user-supplied label across agents. Composite primary key on
+ * (authorId, providerId, connectionId). `scope` buckets identity:
+ * 'per-author' (default), 'shared' (visible to all callers), or
+ * 'caller-supplied' (authorId is a host-app end-user id forwarded via request
+ * context).
+ */
+export const TOOL_PROVIDER_CONNECTIONS_SCHEMA: Record<string, StorageColumn> = {
+  authorId: { type: 'text', nullable: false },
+  providerId: { type: 'text', nullable: false },
+  connectionId: { type: 'text', nullable: false },
+  toolkit: { type: 'text', nullable: false },
+  label: { type: 'text', nullable: true },
+  scope: { type: 'text', nullable: false },
+  createdAt: { type: 'timestamp', nullable: false },
+  updatedAt: { type: 'timestamp', nullable: false },
+};
+
 export const SKILL_VERSIONS_SCHEMA: Record<string, StorageColumn> = {
   id: { type: 'text', nullable: false, primaryKey: true },
   skillId: { type: 'text', nullable: false },
@@ -636,6 +660,7 @@ export const TABLE_SCHEMAS: Record<TABLE_NAMES, Record<string, StorageColumn>> =
     data: { type: 'jsonb', nullable: false },
     updatedAt: { type: 'timestamp', nullable: false },
   },
+  [TABLE_TOOL_PROVIDER_CONNECTIONS]: TOOL_PROVIDER_CONNECTIONS_SCHEMA,
 };
 
 /**
@@ -645,6 +670,10 @@ export const TABLE_SCHEMAS: Record<TABLE_NAMES, Record<string, StorageColumn>> =
 export const TABLE_CONFIGS: Partial<Record<TABLE_NAMES, StorageTableConfig>> = {
   [TABLE_DATASET_ITEMS]: { columns: DATASET_ITEMS_SCHEMA, compositePrimaryKey: ['id', 'datasetVersion'] },
   [TABLE_FAVORITES]: { columns: FAVORITES_SCHEMA, compositePrimaryKey: ['userId', 'entityType', 'entityId'] },
+  [TABLE_TOOL_PROVIDER_CONNECTIONS]: {
+    columns: TOOL_PROVIDER_CONNECTIONS_SCHEMA,
+    compositePrimaryKey: ['authorId', 'providerId', 'connectionId'],
+  },
 };
 
 /**
 
@@ -21,6 +21,7 @@ const PERSISTED_SNAPSHOT_FIELDS = new Set([
   'model',
   'tools',
   'integrationTools',
+  'toolProviders',
   'mcpClients',
   'requestContextSchema',
 ]);
 
@@ -21,4 +21,4 @@ export * from './datasets';
 export * from './experiments';
 export * from './background-tasks';
 export * from './schedules';
-export * from './schedules';
+export * from './tool-provider-connections';
@@ -12,6 +12,7 @@ import type {
   StorageFavoriteType,
   StorageWorkspaceType,
   StorageSkillType,
+  StorageToolProviderConnection,
   StorageWorkflowRun,
   ObservationalMemoryRecord,
   DatasetRecord,
@@ -99,6 +100,11 @@ export class InMemoryDB {
   readonly schedules = new Map<string, Schedule>();
   readonly scheduleTriggers: ScheduleTrigger[] = [];
 
+  /**
+   * Tool provider connections keyed by `${authorId}\u0000${providerId}\u0000${connectionId}`.
+   */
+  readonly toolProviderConnections = new Map<string, StorageToolProviderConnection>();
+
   /**
    * Clears all data from all collections.
    * Useful for testing.
@@ -145,5 +151,6 @@ export class InMemoryDB {
     this.backgroundTasks.clear();
     this.schedules.clear();
     this.scheduleTriggers.length = 0;
+    this.toolProviderConnections.clear();
   }
 }
@@ -46,6 +46,7 @@ export class StoreOperationsInMemory extends StoreOperations {
       mastra_schedule_triggers: new Map(),
       mastra_channel_installations: new Map(),
       mastra_channel_config: new Map(),
+      mastra_tool_provider_connections: new Map(),
     };
   }
 
 
@@ -0,0 +1,63 @@
+import { MastraBase } from '../../../base';
+import type {
+  StorageDeleteToolProviderConnectionInput,
+  StorageListToolProviderConnectionsInput,
+  StorageToolProviderConnection,
+  StorageToolProviderConnectionKey,
+  StorageUpsertToolProviderConnectionInput,
+} from '../../types';
+
+/**
+ * Abstract base class for the tool-provider-connections storage domain.
+ *
+ * Persists a per-author, provider-agnostic registry of authorized tool
+ * provider connections so the UI can surface a stable, user-supplied label
+ * (e.g. "Work Gmail") across agents. Rows are keyed by
+ * `(authorId, providerId, connectionId)`. The label is the only mutable field.
+ *
+ * Adapter-native connection state (status, scopes, expiry) still lives with the
+ * provider — this domain is purely a name lookup.
+ */
+export abstract class ToolProviderConnectionsStorage extends MastraBase {
+  constructor() {
+    super({
+      component: 'STORAGE',
+      name: 'TOOL_PROVIDER_CONNECTIONS',
+    });
+  }
+
+  /** Initialize the store (create tables, indexes, etc). */
+  abstract init(): Promise<void>;
+
+  /**
+   * Fetch a single tool provider connection row. Returns `null` when no row
+   * exists for the given `(authorId, providerId, connectionId)`.
+   */
+  abstract getConnectionById(key: StorageToolProviderConnectionKey): Promise<StorageToolProviderConnection | null>;
+
+  /**
+   * Insert or update a tool provider connection row. Idempotent on
+   * `(authorId, providerId, connectionId)` — the existing label/toolkit are
+   * overwritten. `createdAt` is preserved on update.
+   */
+  abstract upsertConnection(input: StorageUpsertToolProviderConnectionInput): Promise<StorageToolProviderConnection>;
+
+  /**
+   * List tool provider connection rows for the given author. Optionally
+   * narrow by `providerId` and/or `toolkit`. Order is not guaranteed.
+   */
+  abstract listConnectionsByAuthor(
+    input: StorageListToolProviderConnectionsInput,
+  ): Promise<StorageToolProviderConnection[]>;
+
+  /**
+   * Remove a single tool provider connection row. Idempotent — returns
+   * silently when the row does not exist.
+   */
+  abstract deleteConnection(input: StorageDeleteToolProviderConnectionInput): Promise<void>;
+
+  /**
+   * Delete every tool provider connection row. Used by tests.
+   */
+  abstract dangerouslyClearAll(): Promise<void>;
+}
@@ -0,0 +1,2 @@
+export { ToolProviderConnectionsStorage } from './base';
+export { InMemoryToolProviderConnectionsStorage } from './inmemory';
Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,7 @@ export class StoreOperationsInMemory extends StoreOperations {`
`46`	`46`	`mastra_schedule_triggers: new Map(),`
`47`	`47`	`mastra_channel_installations: new Map(),`
`48`	`48`	`mastra_channel_config: new Map(),`
	`49`	`+ mastra_tool_provider_connections: new Map(),`
`49`	`50`	`};`
`50`	`51`	`}`
`51`	`52`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export { ToolProviderConnectionsStorage } from './base';`
	`2`	`+export { InMemoryToolProviderConnectionsStorage } from './inmemory';`