The Executor SDK is the core foundation of the monorepo, providing the contracts and runtime logic for managing integrations, connections, and tool execution. It abstracts away the complexity of multi-tenancy, credential resolution, and long-running execution lifecycles.
The SDK is built around several key interfaces and classes that define how the system interacts with tools and data.
The Executor is the primary entry point for host applications. It is created via the createExecutor factory packages/core/sdk/src/executor.ts21 It manages the stateful interaction between the tool catalog, storage, and the execution fiber.
Key responsibilities include:
Plugins extend the Executor's capabilities. A plugin is defined using the definePlugin helper packages/core/sdk/src/plugin.ts8-23 Plugins can register:
Executor uses a structured dotted-notation for addressing tools, ensuring global uniqueness across integrations and connections.
Format: tools.<integration>.<owner>.<connection>.<tool> packages/core/sdk/src/executor.ts173-176
| Segment | Description |
|---|---|
tools | Constant prefix. |
<integration> | The slug of the registered integration (e.g., github, stripe). |
<owner> | Either org or user, defining the visibility scope. |
<connection> | The name of the specific connection (credential set). |
<tool> | The specific tool name. Can contain dots for nested tools (e.g., repos.get). |
Sources: packages/core/sdk/src/executor.ts173-215 packages/core/sdk/src/ids.ts82
Executor implements a strict multi-tenancy model to ensure data isolation. Every operation is scoped by a triplet: Tenant, Owner, and Subject.
org (shared) or user (private) packages/core/sdk/src/ids.ts76user. For org owners, the subject is typically a constant ORG_SUBJECT packages/core/sdk/src/owner-policy.ts139The following diagram bridges the conceptual multi-tenancy model to the code entities that enforce it.
Diagram: Multi-Tenancy Resolution Flow
Sources: packages/core/sdk/src/plugin.ts66-69 packages/core/sdk/src/executor.ts13-18 packages/core/sdk/src/owner-policy.ts138-141
Plugins are the mechanism for populating the tool catalog. They can register tools in two ways: static and dynamic.
Static tools are defined directly in the plugin definition. They are useful for control-plane operations (e.g., "Add Integration") or utility functions.
tool() helper or StaticToolDecl interface packages/core/sdk/src/plugin.ts121PluginCtx and arguments packages/core/sdk/src/plugin.ts153-157Dynamic tools are resolved at runtime based on external metadata (OpenAPI specs, GraphQL schemas, MCP servers).
Integration record containing a config (e.g., the spec URL) packages/plugins/openapi/src/sdk/plugin.ts122-131executor.listTools() is called, the SDK invokes the plugin's resolveTools or listTools method packages/core/sdk/src/plugin.ts119ToolDef objects packages/core/sdk/src/tool.ts97Diagram: Tool Registration and Invocation
Sources: packages/core/sdk/src/executor.ts1-18 packages/plugins/openapi/src/sdk/plugin.ts40-50 packages/core/sdk/src/core-schema.ts36-43
Plugins can define their own relational schema using definePluginStorageCollection packages/core/sdk/src/plugin-storage.ts208 This storage is automatically partitioned by the OwnerBinding, so a plugin developer never has to manually filter by tenantId or userId packages/core/sdk/src/plugin.ts72-75
Sources: packages/core/sdk/src/plugin-storage.ts207-235 packages/core/sdk/src/plugin.ts77-81