Key Concepts and Terminology

Relevant source files

• README.md
• apps/cli/src/main.ts
• apps/cli/src/tooling.ts
• packages/core/config/package.json
• packages/core/execution/package.json
• packages/core/sdk/package.json
• packages/core/sdk/src/executor.test.ts
• packages/core/sdk/src/executor.ts
• packages/core/sdk/src/index.ts
• packages/core/sdk/src/plugin.ts
• packages/hosts/mcp/src/stdio-integration.test.ts
• packages/kernel/core/package.json
• packages/kernel/runtime-quickjs/package.json
• packages/plugins/file-secrets/package.json
• packages/plugins/graphql/package.json
• packages/plugins/graphql/src/sdk/plugin.test.ts
• packages/plugins/graphql/src/sdk/plugin.ts
• packages/plugins/graphql/src/sdk/store.ts
• packages/plugins/keychain/package.json
• packages/plugins/mcp/package.json
• packages/plugins/onepassword/package.json
• packages/plugins/openapi/package.json
• packages/plugins/openapi/src/sdk/plugin.test.ts
• packages/plugins/openapi/src/sdk/plugin.ts
• tests/presets-reachable.test.ts
• tests/tools-cli.test.ts

This page defines the core domain vocabulary of the Executor system. Understanding these terms is essential for navigating the codebase, as they map directly to the internal data model, directory structure, and API endpoints.

Core Entities

The following terms represent the primary objects managed by the system and stored in the underlying database.

Integration

An Integration represents an upstream API surface or tool provider (e.g., a specific GitHub instance, a Slack workspace, or a custom OpenAPI spec). It defines what tools are available but does not contain user-specific credentials.

• Code Pointers: Defined as Integration in packages/core/sdk/src/integration.ts79-87 The database representation is IntegrationRow in packages/core/sdk/src/core-schema.ts38
• Implementation: Plugins register integrations via ctx.core.integrations.register packages/core/sdk/src/plugin.ts162

Connection

A Connection is a specific, authenticated instance of an Integration. It binds an Integration to a set of credentials (secrets). One Integration can have multiple Connections (e.g., "Work GitHub" and "Personal GitHub").

• Code Pointers: Defined in packages/core/sdk/src/connection.ts22-29 Database representation is ConnectionRow packages/core/sdk/src/core-schema.ts36
• Identifier: Connections are often identified by a ConnectionName, which is a human-readable slug packages/core/sdk/src/ids.ts45

Tool

A Tool is an individual unit of execution (e.g., create_issue or list_messages). Tools are grouped by their parent Connection.

• Code Pointers: The tool definition is ToolDef packages/core/sdk/src/tool.ts143
• Addressing: Tools use a global dotted notation: tools.<integration>.<owner>.<connection>.<tool> packages/core/sdk/src/executor.ts173-177

Toolkit

A Toolkit is a named subset of the tool catalog. It allows grouping tools from different connections into a single logical "kit" with its own specific policy rules.

• Purpose: Used to scope MCP sessions or provide simplified interfaces for specific agent tasks.

---

System Components

Executor

The Executor is the central engine that orchestrates tool discovery, authentication, and execution. It coordinates between Plugins and the Storage layer.

• Code Pointers: The main interface is Executor defined in packages/core/sdk/src/executor.ts214-300
• Factory: Created via createExecutor packages/core/sdk/src/executor.ts1210

Plugin

A Plugin extends the Executor with support for new integration types (OpenAPI, MCP, GraphQL) or credential providers.

• Code Pointers: The plugin contract is AnyPlugin packages/core/sdk/src/plugin.ts111-126
• Registration: Plugins are passed to the Executor at initialization packages/core/sdk/src/executor.ts1210-1215

Sidecar

In the Desktop host, the Sidecar is a supervised background process that runs the Executor daemon. It ensures the API remains available even if the GUI process is busy or restarted.

• Code Pointers: Referenced in the CLI/Daemon logic apps/cli/src/main.ts189-191

Codemode

Codemode (often referred to as kernel/core) refers to the logic responsible for parsing and transforming tool definitions, specifically handling the translation between different schema formats (e.g., JSON Schema to TypeScript types).

• Code Pointers: packages/kernel/core/package.json2-3

---

Execution Lifecycle

Elicitation

Elicitation is the process of suspending a tool's execution to request input or approval from a user. This is critical for OAuth flows or high-stakes actions (like deleting a production database).

• Code Pointers: Managed via ElicitationRequest and ElicitationResponse packages/core/sdk/src/elicitation.ts40-52
• Handler: The onElicitation callback is provided during Executor creation packages/core/sdk/src/executor.ts169-170

Policy

A Policy defines the governance rules for tool usage. It determines if a tool is allow, block, or require_approval.

• Code Pointers: Logic resides in packages/core/sdk/src/policies.ts98-108
• Enforcement: Checked during execute calls in the core SDK.

Vault / Credential Provider

A Vault (or CredentialProvider) is a plugin-driven backend that stores and retrieves secrets (API keys, OAuth tokens).

• Code Pointers: Interface CredentialProvider packages/core/sdk/src/provider.ts109
• Implementations: Include keychain (OS-native), file-secrets, and 1Password.

---

Multi-Tenancy Model

Executor uses a three-tier identity model to partition data and permissions.

Term	Description	Code Reference
Tenant	The top-level organization or account (e.g., a WorkOS Org ID).	Tenant packages/core/sdk/src/ids.ts81
Owner	The visibility scope: either org (shared) or user (private).	Owner packages/core/sdk/src/ids.ts76
Subject	The specific user ID within a tenant (required for user owner scope).	Subject packages/core/sdk/src/ids.ts80

---

External Standards

MCP (Model Context Protocol)

A protocol by Anthropic that allows AI agents to connect to tool servers. Executor acts as both an MCP Client (to ingest tools from MCP servers) and an MCP Host (to expose its entire catalog to agents like Claude Desktop).

• Code Pointers: plugin-mcp packages/plugins/mcp/package.json2

---

Diagrams

Mapping Natural Language to Code Entities

This diagram shows how user-facing concepts (Natural Language Space) map to specific classes and types within the codebase (Code Entity Space).

Diagram: Domain Mapping

Sources: packages/core/sdk/src/core-schema.ts33-43 packages/core/sdk/src/elicitation.ts40-52 packages/core/sdk/src/tool.ts143

Data Flow: Tool Invocation & Elicitation

This diagram traces the flow of a tool call through the system, highlighting where key terminology comes into play.

Diagram: Execution Flow

Sources: packages/core/sdk/src/executor.ts314-450 packages/core/sdk/src/elicitation.ts161-170 packages/core/sdk/src/policies.ts101-102

---

Sources:

• packages/core/sdk/src/executor.ts1-213
• packages/core/sdk/src/ids.ts42-84
• packages/core/sdk/src/plugin.ts59-153
• packages/core/sdk/src/core-schema.ts125-153
• packages/core/sdk/src/elicitation.ts179-190