@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/mcp/framework/aws-sigv4.ts

@@ -0,0 +1,216 @@
+/**
+ * AWS Signature V4 — Lightweight Request Signer
+ *
+ * Implements the AWS Signature Version 4 signing process using only
+ * Node's built-in crypto module. No AWS SDK dependency required.
+ *
+ * Reference:
+ *   https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
+ */
+
+import { createHmac, createHash } from 'node:crypto';
+
+// ─── Public Types ────────────────────────────────────────
+
+export interface AwsSignatureInput {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  service: string;
+  sessionToken?: string;
+}
+
+export interface AwsSignedRequest {
+  url: string;
+  headers: Record<string, string>;
+}
+
+// ─── Helpers ─────────────────────────────────────────────
+
+/** SHA-256 hex digest of a string */
+function sha256(data: string): string {
+  return createHash('sha256').update(data, 'utf8').digest('hex');
+}
+
+/** HMAC-SHA256 returning raw bytes */
+function hmacSha256(key: Buffer | string, data: string): Buffer {
+  return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+
+/** HMAC-SHA256 returning hex string */
+function hmacSha256Hex(key: Buffer | string, data: string): string {
+  return createHmac('sha256', key).update(data, 'utf8').digest('hex');
+}
+
+/** Format a Date as YYYYMMDD'T'HHMMSS'Z' (ISO 8601 basic) */
+function toAmzDate(date: Date): string {
+  return date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+
+/** Extract YYYYMMDD from an AMZ timestamp */
+function toDateStamp(amzDate: string): string {
+  return amzDate.slice(0, 8);
+}
+
+/**
+ * URI-encode a string per AWS rules (RFC 3986, except '/' is encoded
+ * unless the caller explicitly preserves it for path segments).
+ */
+function uriEncode(value: string, encodeSlash = true): string {
+  let encoded = '';
+  for (const ch of value) {
+    if (
+      (ch >= 'A' && ch <= 'Z') ||
+      (ch >= 'a' && ch <= 'z') ||
+      (ch >= '0' && ch <= '9') ||
+      ch === '_' ||
+      ch === '-' ||
+      ch === '~' ||
+      ch === '.'
+    ) {
+      encoded += ch;
+    } else if (ch === '/' && !encodeSlash) {
+      encoded += ch;
+    } else {
+      const bytes = new TextEncoder().encode(ch);
+      for (const b of bytes) {
+        encoded += `%${b.toString(16).toUpperCase().padStart(2, '0')}`;
+      }
+    }
+  }
+  return encoded;
+}
+
+// ─── Signing Logic ───────────────────────────────────────
+
+/**
+ * Derive the signing key via the HMAC chain:
+ *   HMAC(HMAC(HMAC(HMAC("AWS4" + secret, dateStamp), region), service), "aws4_request")
+ */
+function deriveSigningKey(
+  secretAccessKey: string,
+  dateStamp: string,
+  region: string,
+  service: string,
+): Buffer {
+  const kDate = hmacSha256(`AWS4${secretAccessKey}`, dateStamp);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, service);
+  return hmacSha256(kService, 'aws4_request');
+}
+
+/**
+ * Build the canonical query string from URL search params.
+ * Parameters are sorted by key, then by value, and individually URI-encoded.
+ */
+function buildCanonicalQueryString(searchParams: URLSearchParams): string {
+  const params: [string, string][] = [];
+  searchParams.forEach((value, key) => {
+    params.push([uriEncode(key), uriEncode(value)]);
+  });
+  params.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+  return params.map(([k, v]) => `${k}=${v}`).join('&');
+}
+
+// ─── Main Export ─────────────────────────────────────────
+
+/**
+ * Sign an AWS HTTP request using Signature Version 4.
+ *
+ * Returns a new url (unchanged) and headers map that includes
+ * the Authorization header, x-amz-date, x-amz-content-sha256,
+ * and optionally x-amz-security-token.
+ */
+export function signAwsRequest(input: AwsSignatureInput): AwsSignedRequest {
+  const {
+    method,
+    url,
+    headers,
+    body,
+    accessKeyId,
+    secretAccessKey,
+    region,
+    service,
+    sessionToken,
+  } = input;
+
+  const now = new Date();
+  const amzDate = toAmzDate(now);
+  const dateStamp = toDateStamp(amzDate);
+
+  // Parse the URL to extract path and query
+  const parsed = new URL(url);
+  const canonicalUri = uriEncode(parsed.pathname || '/', false);
+  const canonicalQueryString = buildCanonicalQueryString(parsed.searchParams);
+
+  // Hash the payload
+  const payloadHash = sha256(body ?? '');
+
+  // Build working headers (lowercase keys for canonical form)
+  const workingHeaders: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    workingHeaders[k.toLowerCase()] = v.trim();
+  }
+  workingHeaders['host'] = parsed.host;
+  workingHeaders['x-amz-date'] = amzDate;
+  workingHeaders['x-amz-content-sha256'] = payloadHash;
+  if (sessionToken) {
+    workingHeaders['x-amz-security-token'] = sessionToken;
+  }
+
+  // Sorted signed header keys
+  const signedHeaderKeys = Object.keys(workingHeaders).sort();
+  const signedHeaders = signedHeaderKeys.join(';');
+
+  // Build canonical headers (each key:value\n, keys sorted)
+  const canonicalHeaders = signedHeaderKeys
+    .map((k) => `${k}:${workingHeaders[k]}`)
+    .join('\n') + '\n';
+
+  // Step 1: Canonical request
+  const canonicalRequest = [
+    method.toUpperCase(),
+    canonicalUri,
+    canonicalQueryString,
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join('\n');
+
+  // Step 2: String to sign
+  const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    'AWS4-HMAC-SHA256',
+    amzDate,
+    credentialScope,
+    sha256(canonicalRequest),
+  ].join('\n');
+
+  // Step 3: Signing key
+  const signingKey = deriveSigningKey(secretAccessKey, dateStamp, region, service);
+
+  // Step 4: Signature
+  const signature = hmacSha256Hex(signingKey, stringToSign);
+
+  // Build the Authorization header
+  const authorization =
+    `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}, ` +
+    `SignedHeaders=${signedHeaders}, ` +
+    `Signature=${signature}`;
+
+  // Assemble final headers (preserve original casing from input + add signing headers)
+  const finalHeaders: Record<string, string> = { ...headers };
+  finalHeaders['Host'] = parsed.host;
+  finalHeaders['X-Amz-Date'] = amzDate;
+  finalHeaders['X-Amz-Content-Sha256'] = payloadHash;
+  finalHeaders['Authorization'] = authorization;
+  if (sessionToken) {
+    finalHeaders['X-Amz-Security-Token'] = sessionToken;
+  }
+
+  return { url, headers: finalHeaders };
+}

package/src/mcp/framework/credential-resolver.ts

@@ -0,0 +1,128 @@
+/**
+ * MCP Skill Framework — Credential Resolver
+ *
+ * Bridges the enterprise SecureVault to per-skill credentials.
+ * Reads encrypted credentials from the vault, decrypts them, and builds
+ * the appropriate auth headers for each auth type.
+ *
+ * Vault naming convention:
+ *   skill:{skillId}:access_token   — OAuth2 access token
+ *   skill:{skillId}:refresh_token  — OAuth2 refresh token
+ *   skill:{skillId}:api_key        — API key
+ *   skill:{skillId}:token          — Bearer/bot token
+ *   skill:{skillId}:{fieldName}    — Multi-field credentials
+ */
+
+import type { SecureVault } from '../../engine/vault.js';
+import type { AuthConfig, ResolvedCredentials } from './types.js';
+
+export class CredentialResolver {
+  constructor(private vault: SecureVault) {}
+
+  /**
+   * Resolve credentials for a skill from the vault.
+   */
+  async resolve(orgId: string, skillId: string, auth: AuthConfig): Promise<ResolvedCredentials> {
+    const entries = await this.vault.getSecretsByOrg(orgId, 'skill_credential');
+    const prefix = `skill:${skillId}`;
+    const skillEntries = entries.filter(e => e.name.startsWith(prefix));
+
+    switch (auth.type) {
+      case 'oauth2': {
+        const tokenEntry = skillEntries.find(e =>
+          e.name === `${prefix}:access_token` || e.name === prefix
+        );
+        const refreshEntry = skillEntries.find(e => e.name === `${prefix}:refresh_token`);
+
+        if (!tokenEntry) {
+          throw new Error(`No OAuth2 credentials found for skill "${skillId}". Store an access_token in the vault.`);
+        }
+
+        const tokenResult = await this.vault.getSecret(tokenEntry.id);
+        const refreshResult = refreshEntry ? await this.vault.getSecret(refreshEntry.id) : null;
+
+        return {
+          type: 'oauth2',
+          accessToken: tokenResult!.decrypted,
+          refreshToken: refreshResult?.decrypted,
+          expiresAt: tokenEntry.metadata?.expiresAt
+            ? new Date(tokenEntry.metadata.expiresAt)
+            : undefined,
+        };
+      }
+
+      case 'api_key': {
+        const entry = skillEntries.find(e =>
+          e.name === `${prefix}:api_key` || e.name === prefix
+        );
+        if (!entry) {
+          throw new Error(`No API key found for skill "${skillId}". Store an api_key in the vault.`);
+        }
+        const result = await this.vault.getSecret(entry.id);
+        return { type: 'api_key', apiKey: result!.decrypted };
+      }
+
+      case 'token': {
+        const entry = skillEntries.find(e =>
+          e.name === `${prefix}:token` || e.name === prefix
+        );
+        if (!entry) {
+          throw new Error(`No token found for skill "${skillId}". Store a token in the vault.`);
+        }
+        const result = await this.vault.getSecret(entry.id);
+        return { type: 'token', token: result!.decrypted };
+      }
+
+      case 'credentials': {
+        const fields: Record<string, string> = {};
+        for (const field of auth.fields || []) {
+          const entry = skillEntries.find(e => e.name === `${prefix}:${field}`);
+          if (!entry) {
+            throw new Error(`Missing credential field "${field}" for skill "${skillId}".`);
+          }
+          const result = await this.vault.getSecret(entry.id);
+          fields[field] = result!.decrypted;
+        }
+        return { type: 'credentials', fields };
+      }
+
+      default:
+        throw new Error(`Unknown auth type: ${auth.type}`);
+    }
+  }
+
+  /**
+   * Build HTTP auth headers from resolved credentials.
+   */
+  buildHeaders(credentials: ResolvedCredentials, auth: AuthConfig): Record<string, string> {
+    const headerName = auth.headerName || 'Authorization';
+    const prefix = auth.headerPrefix ?? 'Bearer';
+
+    switch (credentials.type) {
+      case 'oauth2':
+        return { [headerName]: `${prefix} ${credentials.accessToken}` };
+
+      case 'api_key':
+        return { [headerName]: `${prefix} ${credentials.apiKey}` };
+
+      case 'token':
+        return { [headerName]: `${prefix} ${credentials.token}` };
+
+      case 'credentials':
+        // Multi-field credentials are handled per-adapter (e.g. AWS signature, basic auth).
+        // The adapter should read ctx.credentials.fields directly.
+        return {};
+
+      default:
+        return {};
+    }
+  }
+
+  /**
+   * Check if credentials exist for a skill (without decrypting).
+   */
+  async hasCredentials(orgId: string, skillId: string): Promise<boolean> {
+    const entries = await this.vault.getSecretsByOrg(orgId, 'skill_credential');
+    return entries.some(e => e.name.startsWith(`skill:${skillId}`));
+  }
+}

package/src/mcp/framework/skill-mcp-framework.ts

@@ -0,0 +1,226 @@
+/**
+ * MCP Skill Framework — Core Orchestrator
+ *
+ * Loads skill adapters, resolves credentials from the vault,
+ * creates per-adapter API executors, and registers tools with
+ * the MCP server. One unified server process serves all skills.
+ *
+ * Integrates:
+ *   - OAuth token auto-refresh (proactive + reactive on 401)
+ *   - Per-adapter rate limiting (token bucket)
+ *   - Skill config loading from community_skill_installed table
+ */
+
+import type { SecureVault } from '../../engine/vault.js';
+import type { SkillAdapter, ToolExecutionContext, ResolvedCredentials } from './types.js';
+import { CredentialResolver } from './credential-resolver.js';
+import { SkillApiExecutor } from './api-executor.js';
+import { OAuthTokenManager } from './oauth-token-manager.js';
+import { RateLimiter } from '../../lib/resilience.js';
+
+export interface FrameworkConfig {
+  vault: SecureVault;
+  orgId: string;
+  agentId: string;
+  /** Installed skill configs keyed by skillId */
+  skillConfigs?: Record<string, Record<string, any>>;
+}
+
+export class SkillMcpFramework {
+  private adapters = new Map<string, SkillAdapter>();
+  private credentialResolver: CredentialResolver;
+  private tokenManager: OAuthTokenManager;
+  private resolvedCredentials = new Map<string, ResolvedCredentials>();
+  private executors = new Map<string, SkillApiExecutor>();
+  private orgId: string;
+  private agentId: string;
+  private skillConfigs: Record<string, Record<string, any>>;
+
+  constructor(private config: FrameworkConfig) {
+    this.credentialResolver = new CredentialResolver(config.vault);
+    this.tokenManager = new OAuthTokenManager(config.vault, config.orgId);
+    this.orgId = config.orgId;
+    this.agentId = config.agentId;
+    this.skillConfigs = config.skillConfigs || {};
+  }
+
+  /**
+   * Register a skill adapter.
+   */
+  register(adapter: SkillAdapter): void {
+    this.adapters.set(adapter.skillId, adapter);
+  }
+
+  /**
+   * Register multiple adapters at once.
+   */
+  registerAll(adapters: SkillAdapter[]): void {
+    for (const a of adapters) this.register(a);
+  }
+
+  /**
+   * Initialize all adapters: resolve credentials, build executors.
+   * Returns a map of skillId → registered tool IDs.
+   * Skills that fail to initialize (e.g. missing credentials) are skipped with a warning.
+   */
+  async initialize(): Promise<Map<string, string[]>> {
+    const result = new Map<string, string[]>();
+
+    for (const [skillId, adapter] of this.adapters) {
+      try {
+        // Resolve credentials from vault
+        const credentials = await this.credentialResolver.resolve(
+          this.orgId, skillId, adapter.auth,
+        );
+        this.resolvedCredentials.set(skillId, credentials);
+
+        // Build auth headers
+        const authHeaders = this.credentialResolver.buildHeaders(credentials, adapter.auth);
+
+        // Optional adapter-level initialization (e.g. Salesforce sets dynamic baseUrl)
+        if (adapter.initialize) {
+          await adapter.initialize(credentials);
+        }
+
+        // Build rate limiter from adapter config
+        let rateLimiter: RateLimiter | undefined;
+        if (adapter.rateLimits) {
+          const rps = adapter.rateLimits.requestsPerSecond ?? 10;
+          const burst = adapter.rateLimits.burstLimit ?? Math.max(rps * 2, 20);
+          rateLimiter = new RateLimiter({ maxTokens: burst, refillRate: rps });
+        }
+
+        // Create the API executor for this adapter
+        const executor = new SkillApiExecutor({
+          baseUrl: adapter.baseUrl,
+          headers: { ...authHeaders, ...(adapter.defaultHeaders || {}) },
+          rateLimiter,
+          skillId: adapter.skillId,
+        });
+        this.executors.set(skillId, executor);
+
+        result.set(skillId, Object.keys(adapter.tools));
+        console.log(
+          `[mcp-skills] ${adapter.name}: ${Object.keys(adapter.tools).length} tools ready`,
+        );
+      } catch (err: any) {
+        console.warn(
+          `[mcp-skills] Skipping ${skillId}: ${err.message}`,
+        );
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Build a new executor for a skill with updated credentials.
+   * Used after token refresh to replace the expired executor.
+   */
+  private rebuildExecutor(skillId: string, adapter: SkillAdapter, credentials: ResolvedCredentials): SkillApiExecutor {
+    const authHeaders = this.credentialResolver.buildHeaders(credentials, adapter.auth);
+    const oldExecutor = this.executors.get(skillId);
+    const executor = new SkillApiExecutor({
+      baseUrl: adapter.baseUrl,
+      headers: { ...authHeaders, ...(adapter.defaultHeaders || {}) },
+      rateLimiter: oldExecutor?.limiter,
+      skillId: adapter.skillId,
+    });
+    this.executors.set(skillId, executor);
+    this.resolvedCredentials.set(skillId, credentials);
+    return executor;
+  }
+
+  /**
+   * Get all initialized tool definitions for MCP registration.
+   * Returns an array of { toolId, description, inputSchema, handler }.
+   *
+   * Each handler wraps the adapter's execute() with:
+   *   - Proactive token refresh (checks expiresAt before each call)
+   *   - Reactive refresh (on 401, attempt one refresh + retry)
+   */
+  getTools(): Array<{
+    toolId: string;
+    skillId: string;
+    description: string;
+    inputSchema: Record<string, any>;
+    handler: (args: Record<string, any>) => Promise<{ content: string; isError?: boolean }>;
+  }> {
+    const tools: ReturnType<typeof this.getTools> = [];
+
+    for (const [skillId, adapter] of this.adapters) {
+      const initialCreds = this.resolvedCredentials.get(skillId);
+      const initialExecutor = this.executors.get(skillId);
+      if (!initialCreds || !initialExecutor) continue; // Skip uninitialized adapters
+
+      for (const [toolId, handler] of Object.entries(adapter.tools)) {
+        tools.push({
+          toolId,
+          skillId,
+          description: handler.description || `${adapter.name}: ${toolId}`,
+          inputSchema: handler.inputSchema,
+          handler: async (args: Record<string, any>) => {
+            // Resolve current credentials (may have been refreshed since initialization)
+            let credentials = this.resolvedCredentials.get(skillId) ?? initialCreds;
+            let executor = this.executors.get(skillId) ?? initialExecutor;
+
+            // Proactive token refresh: check if token expires within 5 minutes
+            if (this.tokenManager.needsRefresh(credentials)) {
+              try {
+                credentials = await this.tokenManager.refreshToken(skillId, credentials, adapter.auth);
+                executor = this.rebuildExecutor(skillId, adapter, credentials);
+              } catch (refreshErr: any) {
+                console.warn(`[mcp-skills] Proactive refresh failed for ${skillId}: ${refreshErr.message}`);
+              }
+            }
+
+            const ctx: ToolExecutionContext = {
+              credentials,
+              skillConfig: this.skillConfigs[skillId] || {},
+              orgId: this.orgId,
+              agentId: this.agentId,
+              apiExecutor: executor,
+            };
+
+            try {
+              const result = await handler.execute(args, ctx);
+              return { content: result.content, isError: result.isError };
+            } catch (err: any) {
+              // Reactive refresh: on 401 with a refresh token, try once
+              if ((err as any).status === 401 && credentials.refreshToken) {
+                try {
+                  const refreshed = await this.tokenManager.refreshToken(skillId, credentials, adapter.auth);
+                  const newExecutor = this.rebuildExecutor(skillId, adapter, refreshed);
+                  const retryCtx: ToolExecutionContext = {
+                    ...ctx,
+                    credentials: refreshed,
+                    apiExecutor: newExecutor,
+                  };
+                  const result = await handler.execute(args, retryCtx);
+                  return { content: result.content, isError: result.isError };
+                } catch (retryErr: any) {
+                  return { content: `Error (${skillId}/${toolId}): ${retryErr.message}`, isError: true };
+                }
+              }
+              return { content: `Error (${skillId}/${toolId}): ${err.message}`, isError: true };
+            }
+          },
+        });
+      }
+    }
+
+    return tools;
+  }
+
+  /**
+   * Get status of all registered adapters.
+   */
+  getStatus(): Array<{ skillId: string; name: string; ready: boolean; toolCount: number }> {
+    return Array.from(this.adapters.entries()).map(([skillId, adapter]) => ({
+      skillId,
+      name: adapter.name,
+      ready: this.executors.has(skillId),
+      toolCount: Object.keys(adapter.tools).length,
+    }));
+  }
+}

package/src/mcp/framework/types.ts

@@ -0,0 +1,130 @@
+/**
+ * MCP Skill Framework — Shared Types
+ *
+ * Defines the interfaces that every skill adapter implements.
+ * The framework handles boilerplate (auth, retry, circuit breaking, vault);
+ * adapters focus on API endpoint mapping and response formatting.
+ */
+
+// ─── Auth Configuration ─────────────────────────────────
+
+export type AuthType = 'oauth2' | 'api_key' | 'token' | 'credentials';
+
+export interface AuthConfig {
+  type: AuthType;
+
+  // oauth2
+  provider?: string;
+  scopes?: string[];
+
+  // api_key / token
+  headerName?: string;      // Default: 'Authorization'
+  headerPrefix?: string;    // Default: 'Bearer'
+  envVar?: string;
+
+  // credentials (multi-field, e.g. AWS accessKeyId + secretAccessKey)
+  fields?: string[];
+  envVars?: Record<string, string>;
+}
+
+export interface ResolvedCredentials {
+  type: AuthType;
+  accessToken?: string;
+  refreshToken?: string;
+  apiKey?: string;
+  token?: string;
+  fields?: Record<string, string>;
+  expiresAt?: Date;
+}
+
+// ─── API Executor ────────────────────────────────────────
+
+export interface ApiRequestOptions {
+  method: string;
+  url?: string;             // Full URL override
+  path?: string;            // Appended to adapter's baseUrl
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+  body?: any;
+  formEncoded?: boolean;    // Send as application/x-www-form-urlencoded
+  multipart?: boolean;      // Send as multipart/form-data
+  rawBody?: Buffer | Uint8Array;  // Pre-built body (bypass JSON/form serialization)
+  rawContentType?: string;  // Content-Type for rawBody
+  timeoutMs?: number;
+}
+
+export interface ApiExecutor {
+  get(path: string, query?: Record<string, string>): Promise<any>;
+  post(path: string, body?: any): Promise<any>;
+  put(path: string, body?: any): Promise<any>;
+  patch(path: string, body?: any): Promise<any>;
+  delete(path: string, query?: Record<string, string>): Promise<any>;
+  request(opts: ApiRequestOptions): Promise<any>;
+}
+
+// ─── Tool Handler ────────────────────────────────────────
+
+export interface ToolResult {
+  /** Text content returned to the LLM */
+  content: string;
+  /** Structured data for activity logging */
+  metadata?: Record<string, any>;
+  /** Mark as error */
+  isError?: boolean;
+}
+
+export interface ToolExecutionContext {
+  credentials: ResolvedCredentials;
+  skillConfig: Record<string, any>;
+  orgId: string;
+  agentId: string;
+  apiExecutor: ApiExecutor;
+}
+
+export interface ToolHandler {
+  /** JSON Schema for the tool's input parameters */
+  inputSchema: Record<string, any>;
+  /** Human-readable description for the LLM */
+  description?: string;
+  /** Execute the tool */
+  execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult>;
+}
+
+// ─── Config Schema ──────────────────────────────────────
+
+export interface ConfigField {
+  type: 'string' | 'number' | 'boolean' | 'select' | 'secret';
+  label: string;
+  description?: string;
+  required?: boolean;
+  default?: any;
+  placeholder?: string;
+  options?: { label: string; value: string }[];
+}
+
+// ─── Skill Adapter ───────────────────────────────────────
+
+export interface SkillAdapter {
+  /** Must match the community-skills manifest id */
+  skillId: string;
+  /** Human-readable skill name */
+  name: string;
+  /** Base URL for all API calls (e.g. 'https://slack.com/api') */
+  baseUrl: string;
+  /** Auth configuration — matches manifest auth block */
+  auth: AuthConfig;
+  /** Extra default headers sent with every request */
+  defaultHeaders?: Record<string, string>;
+  /** Tool implementations keyed by tool ID */
+  tools: Record<string, ToolHandler>;
+  /** Called once after credentials are resolved (e.g. set dynamic base URL) */
+  initialize?(credentials: ResolvedCredentials): Promise<void>;
+  /** Per-adapter rate limits for proactive throttling */
+  rateLimits?: {
+    requestsPerSecond?: number;
+    requestsPerMinute?: number;
+    burstLimit?: number;
+  };
+  /** JSON Schema for configurable fields (rendered in dashboard) */
+  configSchema?: Record<string, ConfigField>;
+}