Skip to content
Leverage AI Developer Support

Connector Provider Changes

Connector work is production-critical. A provider change usually crosses domain registry, customer CMS seed data, API runtime, auth, web UX, and eval/smoke coverage.

For a new connector, start with Add A New Connector and the Connector Implementation Intake / New Connector Implementation templates in PROMPT_TEMPLATES.md.

Expected Path

Section titled “Expected Path”
  1. Read docs/features/connectors/spec.md and the provider-specific support-dev page if one exists.
  2. Use the prompt template when the work needs assistant help, provider research, or scope discovery.
  3. Update the shared domain registry for connector identity, OAuth binding, modes, resources, defaults, and connection scope.
  4. Add or update API runtime manifests/extensions for indexed sync, live adapters, resource-list adapters, option dependencies, and real-provider smoke hooks.
  5. Check whether customer CMS seed/default connector data needs to change.
  6. Update web/API/shared contracts only through the canonical mode model: supportedModes, enabledModes, and domain-oriented live tool ids.
  7. Add or update deterministic tests, connector eval coverage, and provider smoke coverage.
  8. Let the assistant use evals and Agent Browser when they can verify connector answer accuracy, citations, source panels, recovery states, and visible connect/settings behavior in the real local app.
  9. Keep manual testing in the handoff. A human should still exercise the important connector workflow before PR handoff when the change affects user-facing setup, chat answers, citations, or recovery behavior.
  10. Update support-dev pages after the runtime truth is clear.

Live-First, Indexed-Later Loop

Section titled “Live-First, Indexed-Later Loop”

Use this loop for most new built-in connectors:

  1. Fill PROMPT_TEMPLATES.md with connector keys, provider objects, facets, auth scopes, target live domain, unsupported surfaces, and whether the first pass is live-first-indexed-later.
  2. Implement or reuse the canonical live domain before provider code. New provider mechanics should normalize into shared contracts such as work-item, code-repository, mail, calendar, contact, workspace-chat, or file-resource.
  3. Keep provider-specific code in the owning adapter/manifest: upstream endpoints, scopes, pagination, rate-limit handling, and provider payload normalization. Shared source selection, answer policy, focus, mode behavior, resource scoping, and prompt-pack generation should stay connector-agnostic.
  4. Build a provider capability/facet checklist from official docs. If facets have first-class provider APIs, expose bounded facet inventory instead of inferring configured metadata from sampled object rows. Check provider facet sort/page limits before applying answer caps so late-page metadata, future-dated facets, or alphabetically late facets are not hidden accidentally.
  5. Add deterministic evals with neutral provider-shaped fixtures, including positive rows, wrong-scope decoys, stale data, inaccessible named parent resources, same-name accessible suggestions, unsupported surfaces, no-match cases, and broad inventory cases where one parent resource could otherwise fill the result cap.
  6. Verify follow-up context. A user confirmation of a suggested parent resource should keep the previous live domain/query mode and apply the corrected resource, while an explicit source switch should move domains.
  7. Verify explicit source prompts stay on the requested live domain. List/count/facet prompts should not show unrelated table-data progress or run table tools unless files or tables are explicitly in scope.
  8. Add real-provider smoke for upstream auth/payload drift and local prompt-pack coverage for browser-backed answer quality. Leave prompt-pack chats visible for human review unless privacy or CI cleanup requires --delete-chats. Review final wording for source discipline and checked-scope language such as “checked 20 repositories”; avoid internal retrieval terms in answers.
  9. Defer indexed sync, Meltano taps, embeddings, retained chunks, or vectors until measured live-query failures, provider latency/rate limits, customer retention requirements, or accepted product/security criteria justify stored copies.

See Live Query for live-domain behavior and Chat Orchestration for answer-quality and source-selection verification.

Current Implemented Providers

Section titled “Current Implemented Providers”
  • Confluence
  • Gmail
  • Google Calendar
  • Google Contacts
  • Google Drive
  • GitHub Issues
  • GitHub Pull Requests
  • GitHub Repositories
  • Jira
  • Microsoft Calendar
  • Microsoft Contacts
  • Odoo
  • OneDrive
  • Outlook
  • Slack

See All Connectors and Planned Connectors for the registry-level catalog.

Fail-Closed Rules

Section titled “Fail-Closed Rules”
  • Registry drift must return a validated 4xx domain error instead of permissive defaults.
  • Missing runtime support must not silently make a connector addable.
  • Customer CMS policy may curate availability, but OAuth credentials remain deployment-owned secrets.
  • Connector OAuth is not workforce SSO; do not reuse SSO provider ids or semantics.

Canonical Sources

Section titled “Canonical Sources”
  • docs/features/connectors/spec.md
  • docs/features/connectors/spec-mcp-extensions.md
  • PROMPT_TEMPLATES.md
  • packages/domain/src/connectors/connectorRegistry.ts
  • apps/api/src/connectors/connectorRuntimeExtensions.ts
  • apps/api/src/connectors/providerManifests.ts
  • apps/cms-customer/src/connectors/defaultConnectorCatalog.ts
  • apps/cms-customer/src/connectors/seedDefaultConnectorCatalog.ts
  • apps/web/app/pages/connectors.vue