The Executor system is built on a modular, layered architecture designed to provide a unified tool-calling interface across diverse environments, from local CLI daemons to distributed cloud workers. The architecture decouples the tool definition (Integrations) from their authorization (Connections) and execution (Runtimes).
The architecture is composed of five primary layers that work together to resolve, authorize, and execute tools.
The foundation of the system is the @executor-js/sdk. It defines the core domain models: Integration, Connection, Tool, and Executor packages/core/sdk/src/executor.ts85-90 It provides the createExecutor factory, which aggregates plugins and provides a high-level API for tool discovery and invocation packages/core/sdk/src/executor.ts160-170
Plugins are the primary mechanism for extending Executor. They register "Static" or "Dynamic" tools and handle specific protocols like OpenAPI, MCP, or GraphQL packages/core/sdk/src/plugin.ts110-125 Plugins also define how credentials (secrets) are stored and retrieved through the CredentialProvider interface packages/core/sdk/src/provider.ts100-110
The ExecutionEngine manages the lifecycle of a tool call. It handles "Elicitation"—the process of pausing execution to request user input or approval packages/core/sdk/src/elicitation.ts160-170 Tools are executed in isolated environments, such as the QuickJS-based sandbox for local safety or dynamic workers for cloud scale packages/core/sdk/src/executor.ts45-55
FumaDB is a database abstraction layer that allows the same business logic to run against SQLite (local), PostgreSQL (cloud), or an in-memory store (tests) packages/core/sdk/src/executor.ts3-5 It provides a type-safe query builder and schema management packages/core/sdk/src/core-schema.ts125-150
Hosts (CLI, Desktop, Cloud) consume the SDK and the @executor-js/api package to expose the system via HTTP or local IPC apps/cli/package.json25-30 The API layer groups handlers into logical sets like /tools, /connections, and /integrations packages/react/package.json6-15
This diagram shows how the core SDK acts as the orchestrator between external interfaces (API/Hosts) and the internal logic (Plugins/DB).
Sources: apps/cli/package.json25-31 apps/cloud/package.json35-55 packages/core/sdk/src/executor.ts1-20
The following diagram bridges the conceptual layers to the specific classes and interfaces found in the codebase.
Sources: packages/core/sdk/src/executor.ts178-210 packages/core/sdk/src/plugin.ts110-130 packages/core/sdk/src/fuma-runtime.ts32-38
The SDK provides a multi-tenant model using Tenant, Owner, and Subject identifiers to scope tools and connections. Plugins use a PluginCtx to access storage and secret management.
For details, see Executor SDK and Plugin System.
The system supports multiple runtimes. Local environments typically use @executor-js/runtime-quickjs for executing untrusted tool code in a WASM-based sandbox.
For details, see Execution Engine and Sandboxed Runtimes.
FumaDB enables "Local-First" development. Developers can use memoryAdapter for rapid testing and switch to drizzle or kysely adapters for production deployments.
For details, see FumaDB: Database Abstraction Layer.
The @executor-js/api package uses Effect.HttpApi to define a contract-first server. This allows for automatic client generation and consistent error handling across all host types.
For details, see API Layer and HTTP Server.
Executor includes a comprehensive OAuth service that handles the complexity of dynamic client registration, token refreshing, and secure credential storage. For details, see OAuth and Authentication.
| Path | Description |
|---|---|
packages/core/sdk | The core kernel and domain logic. |
packages/core/execution | The execution engine and elicitation logic. |
packages/plugins/* | Individual protocol and secret management plugins. |
packages/kernel/* | Low-level runtimes (QuickJS, etc.). |
apps/* | Host applications that compose the SDK. |
Sources: package.json23-30 bun.lock31-80
Refresh this wiki