---
title: "Extending Executor"
description: "How to add new source support without breaking the current architecture."
---

The best way to extend executor is to respect the current boundaries instead of stretching the core model.

## First question: is it really a source?

Not every new integration should be modeled as a source.

Use the source model when the thing is:

- a persistent external system
- with install-local configuration
- with auth state
- that materializes into callable tools

If the new thing is really:

- a local tool library
- a package bundle
- a browser automation runtime

then it may need a different top-level primitive instead of being shoved into the source model.

## If it is a source, add an adapter

The happy path for a new integration is:

1. define the adapter key and family
2. define the connect and binding config shape
3. materialize into documents, schema bundles, and operations
4. implement invocation
5. add tests against the canonical model

The adapter should absorb provider-specific logic so the core does not have to.

## What a new adapter should not do

Avoid these patterns:

- adding new provider-specific columns to generic tables because one adapter wants them
- storing expanded presentation output as canonical truth
- bypassing the operation layer and invoking directly from raw documents
- treating auth as provider-specific ad hoc fields on the source row

Those are the patterns that lead back to churn.

## The standard for a good extension

A good new adapter should make the core system feel boring.

That means:

- persistence still looks like recipe/revision/operations
- auth still flows through the same credential/session primitives
- discovery and inspection still work through the same catalog ideas
- execution still delegates through the same tool and adapter boundaries

If a new adapter needs deep new behavior in all of those places, that is usually a sign it may be a new primitive, not just a new adapter.

## What feels like the next natural extensions

The current architecture is well-suited to future additions like:

- Google Discovery imports
- Postman collection imports
- snippet bundles
- richer auth material providers

Those should mostly be adapter and auth-layer work, not another persistence redesign.

## Why this is the best setup

The current setup is not trying to be abstract for its own sake.
It is trying to keep the codebase in a state where:

- core concepts stay stable
- new support lands as extensions
- source support does not require philosophy rewrites every few weeks

That is the real reason the system is shaped around adapters, recipes, revisions, operations, and actor-scoped credentials.