The Promise SDK provides a developer-friendly, Promise-based entry point for embedding the Executor engine into TypeScript and JavaScript applications. While the internal core of Executor is built using the Effect library for robust error handling and concurrency, the @executor-js/sdk/promise entry point abstracts these details away, allowing developers to use standard async/await patterns packages/core/execution/src/promise.ts1-11
The primary way to instantiate the SDK is via the createExecutor factory. This creates an Executor instance that manages integrations, connections, and tool execution using standard JavaScript types packages/core/execution/src/promise.ts21
| Entity | Description |
|---|---|
ExecutionEngine | The high-level interface for running sandboxed code and managing paused executions packages/core/execution/src/promise.ts39-56 |
createExecutor | The main factory function for initializing the SDK. |
CredentialProvider | Interface for plugging in secret storage (e.g., Keychain, 1Password, or In-Memory) packages/core/execution/src/tool-invoker.test.ts18 |
ElicitationHandler | A callback function used to handle interactive requests (like OAuth flows or form inputs) during code execution packages/core/execution/src/promise.ts32 |
This diagram illustrates how the PromiseExecutor facade maps to the internal EffectExecutor used by the ExecutionEngine.
Title: Promise SDK to Effect Core Mapping
Sources: packages/core/execution/src/promise.ts63-138 packages/core/execution/src/promise.ts146-155
The ExecutionEngine is responsible for taking TypeScript code, executing it in a sandbox, and resolving tool calls through the configured Executor packages/core/execution/src/engine.ts29-33
When code is executed, it may encounter tools that require human intervention (e.g., OAuth authorization or manual approval). The engine supports two primary execution modes:
execute): Requires an ElicitationHandler to resolve pauses immediately packages/core/execution/src/promise.ts40-43executeWithPause): Returns a status: "paused" result if a tool requires elicitation, allowing the execution to be resumed later via a unique executionId packages/core/execution/src/engine.ts35-42Title: Execution Engine Data Flow
Sources: packages/core/execution/src/engine.ts15-23 packages/core/execution/src/tool-invoker.ts48-65
The SDK requires a CredentialProvider to handle authentication for integrations. The provider interface allows for various backends:
@executor-js/plugin-keychain (OS-native) or @executor-js/plugin-onepassword examples/all-plugins/package.json12-19A provider must implement get, set, has, and list methods, returning Effect (internally) or Promise (in the SDK) wrappers around the underlying storage packages/core/execution/src/tool-invoker.test.ts131-144
The repository provides two primary examples for SDK usage:
Located in examples/docs-sdk-quickstart, this demonstrates the minimal setup required to run the engine with the OpenAPI plugin examples/docs-sdk-quickstart/package.json1-20
Located in examples/all-plugins, this shows a comprehensive setup including:
The engine includes utilities to format execution results into human-readable or model-readable text packages/core/execution/src/engine.ts76-82
Sources:
Refresh this wiki