feat(capabilities): sibling-aware credential routing with isDefault

bubblelab-pearl · bubblelab-pearl · commit 94572944d1ff · 2026-04-29T05:03:05.000-07:00
diff --git a/packages/bubble-core/src/bubbles/service-bubble/ai-agent-before-action.ts b/packages/bubble-core/src/bubbles/service-bubble/ai-agent-before-action.ts
@@ -123,19 +123,17 @@ function injectFlowMasterDynamicState(deps: BeforeActionDeps): void {
     if (!entries.length) continue;
     if (!params.credentials) params.credentials = {};
     (params.credentials as Record<string, string>)[credType] = entries[0].value;
-    if (entries.length > 1) {
-      if (!params.credentialPool)
-        params.credentialPool = {} as Record<
-          CredentialType,
-          Array<{ id: number; name: string; value: string }>
-        >;
-      (
-        params.credentialPool as Record<
-          string,
-          Array<{ id: number; name: string; value: string }>
-        >
-      )[credType] = entries;
-    }
+    if (!params.credentialPool)
+      params.credentialPool = {} as Record<
+        CredentialType,
+        Array<{ id: number; name: string; value: string }>
+      >;
+    (
+      params.credentialPool as Record<
+        string,
+        Array<{ id: number; name: string; value: string }>
+      >
+    )[credType] = entries;
   }
 }
 
diff --git a/packages/bubble-core/src/bubbles/service-bubble/ai-agent.ts b/packages/bubble-core/src/bubbles/service-bubble/ai-agent.ts
@@ -5,6 +5,8 @@ import {
   CredentialType,
   BUBBLE_CREDENTIAL_OPTIONS,
   RECOMMENDED_MODELS,
+  getCanonicalCredentialType,
+  getSiblingCredentialTypes,
 } from '@bubblelab/shared-schemas';
 import { StateGraph, MessagesAnnotation } from '@langchain/langgraph';
 import { ChatOpenAI } from '@langchain/openai';
@@ -363,6 +365,8 @@ const AIAgentParamsSchema = z.object({
           id: z.number(),
           name: z.string(),
           value: z.string(),
+          isDefault: z.boolean().optional(),
+          attributes: z.record(z.string(), z.string()).optional(),
         })
       )
     )
@@ -1494,44 +1498,75 @@ export class AIAgentBubble extends ServiceBubble<
               ? { ...this.params.credentials }
               : undefined;
 
+            type PoolEntry = { id: number; name: string; value: string };
+            const findInPool = (
+              pool: PoolEntry[] | undefined,
+              selector: string | number
+            ): PoolEntry | undefined => {
+              if (!pool) return undefined;
+              let match: PoolEntry | undefined;
+              if (typeof selector === 'string') {
+                const sel = selector.toLowerCase();
+                match = pool.find((c) => c.name.toLowerCase() === sel);
+                if (!match) {
+                  match = pool.find((c) => c.name.toLowerCase().includes(sel));
+                }
+              }
+              if (!match && typeof selector === 'number') {
+                match = pool.find((c) => c.id === selector);
+              }
+              if (!match && typeof selector === 'string') {
+                const asNum = Number(selector);
+                if (!Number.isNaN(asNum)) {
+                  match = pool.find((c) => c.id === asNum);
+                }
+              }
+              return match;
+            };
+
+            let overrideTypes: string[] | undefined;
             if (
               credentialOverrides &&
               this.params.credentialPool &&
               subAgentCredentials
             ) {
+              overrideTypes = [];
               for (const [credType, credSelector] of Object.entries(
                 credentialOverrides
               )) {
-                const pool =
-                  this.params.credentialPool[credType as CredentialType];
-                if (!pool) continue;
-
-                // Match by name first (string), fall back to ID (number)
-                let match: (typeof pool)[number] | undefined;
-                if (typeof credSelector === 'string') {
-                  const sel = credSelector.toLowerCase();
-                  // Exact match first, then substring (handles "email (label)" format)
-                  match = pool.find((c) => c.name.toLowerCase() === sel);
-                  if (!match) {
-                    match = pool.find((c) =>
-                      c.name.toLowerCase().includes(sel)
+                let matchedType = credType as CredentialType;
+                let match = findInPool(
+                  this.params.credentialPool[matchedType],
+                  credSelector
+                );
+                // Sibling fallback: when the requested type's pool has no
+                // match, walk paired sibling types (e.g. SLACK_CRED ↔
+                // SLACK_API) so the master can route across OAuth/API-key
+                // accounts of the same logical provider.
+                if (!match) {
+                  for (const sibling of getSiblingCredentialTypes(
+                    credType as CredentialType
+                  )) {
+                    if (sibling === matchedType) continue;
+                    const found = findInPool(
+                      this.params.credentialPool[sibling],
+                      credSelector
                     );
-                  }
-                }
-                if (!match && typeof credSelector === 'number') {
-                  match = pool.find((c) => c.id === credSelector);
-                }
-                // Also try parsing string as number for ID fallback
-                if (!match && typeof credSelector === 'string') {
-                  const asNum = Number(credSelector);
-                  if (!Number.isNaN(asNum)) {
-                    match = pool.find((c) => c.id === asNum);
+                    if (found) {
+                      match = found;
+                      matchedType = sibling;
+                      break;
+                    }
                   }
                 }
 
                 if (match) {
-                  subAgentCredentials[credType as CredentialType] = match.value;
+                  subAgentCredentials[matchedType] = match.value;
                 }
+                // Record the resolved real type (or the requested type when
+                // unmatched) so downstream provider routing
+                // (data-analyst/utils.ts) sees what was actually selected.
+                overrideTypes.push(matchedType);
               }
             }
 
@@ -1540,7 +1575,8 @@ export class AIAgentBubble extends ServiceBubble<
             if (credentialOverrides && this.context?.executionMeta) {
               (
                 this.context.executionMeta as Record<string, unknown>
-              )._credentialOverrideTypes = Object.keys(credentialOverrides);
+              )._credentialOverrideTypes =
+                overrideTypes ?? Object.keys(credentialOverrides);
             }
 
             // Dynamic credentials (from manage_capability set_credential) are
@@ -1810,6 +1846,55 @@ export class AIAgentBubble extends ServiceBubble<
       }
     }
 
+    // Prune non-pinned siblings when a sibling pair is in play and the master
+    // (via use-capability `credentials` override) or a saved-flow capConfig
+    // explicitly pinned a specific sibling type. Without this, capabilities
+    // whose runtime helper does `oauth ?? api` would silently pick the OAuth
+    // default and ignore the pin.
+    const overrideTypes = (
+      this.context?.executionMeta as Record<string, unknown> | undefined
+    )?._credentialOverrideTypes as string[] | undefined;
+    const pinned = new Set<string>([
+      ...Object.keys(capConfig.credentials ?? {}),
+      ...(overrideTypes ?? []),
+    ]);
+    if (pinned.size > 0) {
+      for (const ct of Object.keys(resolved)) {
+        if (pinned.has(ct)) continue;
+        const siblings = getSiblingCredentialTypes(ct as CredentialType);
+        if (siblings.some((s) => pinned.has(s))) {
+          delete resolved[ct as CredentialType];
+        }
+      }
+    }
+
+    // Sibling default pre-prune: when no explicit pin AND a sibling pair is
+    // fully declared AND exactly one sibling type has a credential marked as
+    // user default (`isDefault: true` in the pool), drop the unmarked sibling
+    // so the cap's `oauth ?? api` collapses to the user's preferred auth
+    // method without requiring an override.
+    if (pinned.size === 0 && this.params.credentialPool) {
+      const pool = this.params.credentialPool;
+      const seenCanonicals = new Set<CredentialType>();
+      for (const ct of [...Object.keys(resolved)] as CredentialType[]) {
+        const canonical = getCanonicalCredentialType(ct);
+        if (seenCanonicals.has(canonical)) continue;
+        seenCanonicals.add(canonical);
+        const siblings = getSiblingCredentialTypes(ct);
+        if (siblings.length < 2) continue;
+        const present = siblings.filter((s) => resolved[s] !== undefined);
+        if (present.length < 2) continue;
+        const marked = present.filter((s) =>
+          pool[s]?.some((e) => e.isDefault === true)
+        );
+        if (marked.length === 1) {
+          for (const s of siblings) {
+            if (s !== marked[0]) delete resolved[s as CredentialType];
+          }
+        }
+      }
+    }
+
     return resolved;
   }
 
diff --git a/packages/bubble-core/src/bubbles/service-bubble/capability-pipeline.ts b/packages/bubble-core/src/bubbles/service-bubble/capability-pipeline.ts
@@ -1,6 +1,8 @@
 import type { BubbleContext } from '../../types/bubble.js';
 import {
   RECOMMENDED_MODELS,
+  getCanonicalCredentialType,
+  getSiblingCredentialTypes,
   type CredentialType,
   type CredentialPoolEntry,
 } from '@bubblelab/shared-schemas';
@@ -161,28 +163,60 @@ export async function applyCapabilityPreprocessing(
             ...(def.metadata.optionalCredentials ?? []),
           ];
           if (allCredTypes.length > 0) {
+            const declaredSet = new Set<CredentialType>(allCredTypes);
             const credLines: string[] = [];
             for (const credType of allCredTypes) {
               const isSet = !!resolvedCreds[credType];
               const pool = credentialPool?.[credType];
-              if (isSet && pool && pool.length > 1) {
-                // Multiple accounts available — list them
-                const names = pool
-                  .map(
-                    (e) => `"${e.name.replace(/[\n\r]/g, ' ').slice(0, 100)}"`
-                  )
-                  .join(', ');
+
+              if (!isSet) {
+                // Sibling-aware suppression: when this cap declared a paired
+                // sibling type (e.g. AIRTABLE_OAUTH + AIRTABLE_CRED) and the
+                // other one is set, omit this redundant "✗ NOT SET" row.
+                // When neither sibling is set, emit only the canonical row
+                // so the master sees one entry instead of two.
+                const otherSiblings = getSiblingCredentialTypes(
+                  credType
+                ).filter((s) => s !== credType && declaredSet.has(s));
+                if (otherSiblings.length > 0) {
+                  if (otherSiblings.some((s) => !!resolvedCreds[s])) continue;
+                  const canonical = getCanonicalCredentialType(credType);
+                  if (credType !== canonical && declaredSet.has(canonical))
+                    continue;
+                }
                 credLines.push(
-                  `${credType}: ✓ SET (${pool.length} accounts: ${names})`
+                  `${credType}: ✗ NOT SET — use initiate-credential-creation to connect`
                 );
-              } else if (isSet) {
-                const name = pool?.[0]?.name;
+                continue;
+              }
+
+              const formatEntry = (
+                e: CredentialPoolEntry,
+                maxNameLen: number
+              ): string => {
+                const safeName = e.name
+                  .replace(/[\n\r]/g, ' ')
+                  .slice(0, maxNameLen);
+                const defaultTag = e.isDefault ? ' (default)' : '';
+                const attrPairs = e.attributes
+                  ? Object.entries(e.attributes)
+                      .map(([k, v]) => `${k}=${v}`)
+                      .join(', ')
+                  : '';
+                const attrTag = attrPairs ? ` [${attrPairs}]` : '';
+                return `"${safeName}"${defaultTag}${attrTag}`;
+              };
+
+              if (pool && pool.length > 1) {
+                // Multiple accounts available — list them
+                const names = pool.map((e) => formatEntry(e, 100)).join(', ');
                 credLines.push(
-                  `${credType}: ✓ SET${name ? ` ("${name.replace(/[\n\r]/g, ' ').slice(0, 80)}")` : ''}`
+                  `${credType}: ✓ SET (${pool.length} accounts: ${names})`
                 );
               } else {
+                const entry = pool?.[0];
                 credLines.push(
-                  `${credType}: ✗ NOT SET — use initiate-credential-creation to connect`
+                  `${credType}: ✓ SET${entry ? ` (${formatEntry(entry, 80)})` : ''}`
                 );
               }
             }
diff --git a/packages/bubble-runtime/src/injection/BubbleInjector.ts b/packages/bubble-runtime/src/injection/BubbleInjector.ts
@@ -615,8 +615,11 @@ export class BubbleInjector {
           this.injectCredentialsIntoBubble(bubble, credentialMapping);
         }
 
-        // For ai-agent bubbles, build and inject credential pool when
-        // multiple user credentials exist for the same credential type
+        // For ai-agent bubbles, build and inject credential pool so the
+        // master can disambiguate accounts by name. Populated for any
+        // non-empty type, including singletons — the prompt rendering and
+        // sibling-aware use-capability lookup both rely on pool entries
+        // existing.
         if (bubble.bubbleName === 'ai-agent' && userCreds.length > 0) {
           const credsByType = new Map<
             CredentialType,
@@ -637,19 +640,13 @@ export class BubbleInjector {
               value: this.escapeString(uc.secret),
             });
           }
-          // Only inject pool if at least one type has multiple credentials
-          const hasMultiple = Array.from(credsByType.values()).some(
-            (entries) => entries.length > 1
-          );
-          if (hasMultiple) {
+          if (credsByType.size > 0) {
             const pool: Record<
               string,
               Array<{ id: number; name: string; value: string }>
             > = {};
             for (const [credType, entries] of credsByType) {
-              if (entries.length > 1) {
-                pool[credType] = entries;
-              }
+              pool[credType] = entries;
             }
             this.injectCredentialPoolIntoBubble(bubble, pool);
           }
diff --git a/packages/bubble-shared-schemas/src/credential-schema.ts b/packages/bubble-shared-schemas/src/credential-schema.ts
@@ -32,6 +32,15 @@ export interface CredentialPoolEntry {
   id: number;
   name: string;
   value: string;
+  /** True when the user marked this credential as the default for its type. */
+  isDefault?: boolean;
+  /**
+   * Per-credential-type display hints surfaced to the master agent's prompt
+   * (e.g. `{ workspace: "Bubble Lab", authMethod: "oauth", hasUserToken: "yes" }`).
+   * Populated by an extractor in Pro that reads `userCredentials.metadata`.
+   * Display-only — capability runtime code should not branch on these.
+   */
+  attributes?: Record<string, string>;
 }
 
 /**
