Glossary

Relevant source files

• .github/workflows/ci.yml
• .github/workflows/pkg-pr-new.yml
• .github/workflows/preview-sweep.yml
• .github/workflows/preview.yml
• .github/workflows/publish-desktop.yml
• .github/workflows/publish-executor-package.yml
• .github/workflows/publish-selfhost-docker.yml
• .github/workflows/release.yml
• .gitignore
• README.md
• apps/cli/package.json
• apps/cli/src/main.ts
• apps/cli/src/tooling.ts
• apps/cloud/package.json
• apps/cloud/src/api/protected.test.ts
• apps/cloud/src/env-augment.d.ts
• apps/cloud/src/mcp/session-durable-object.ts
• apps/cloud/src/server.ts
• apps/cloud/src/web/pages/login.tsx
• apps/cloud/worker-configuration.d.ts
• apps/cloud/wrangler.jsonc
• apps/desktop/package.json
• apps/host-cloudflare/.gitignore
• apps/host-cloudflare/scripts/preview.ts
• apps/local/package.json
• apps/marketing/astro.config.mjs
• apps/marketing/package.json
• apps/marketing/public/og-image.png
• apps/marketing/public/pattern-graph-paper.svg
• apps/marketing/src/components/LegalLayout.astro
• apps/marketing/src/components/animated-beam-demo.tsx
• apps/marketing/src/components/context-bloat-demo.tsx
• apps/marketing/src/components/ui/animated-beam.tsx
• apps/marketing/src/env.d.ts
• apps/marketing/src/layouts/Layout.astro
• apps/marketing/src/lib/github.ts
• apps/marketing/src/lib/utils.ts
• apps/marketing/src/middleware.ts
• apps/marketing/src/pages/index.astro
• apps/marketing/src/styles/global.css
• apps/marketing/wrangler.toml
• bun.lock
• e2e/CHANGELOG.md
• e2e/package.json
• e2e/scenarios/mcp-catalog-sync-ui.test.ts
• e2e/scenarios/mcp-catalog-sync.test.ts
• e2e/scenarios/run-panel-auto-approve.test.ts
• e2e/setup/cloud.globalsetup.ts
• e2e/setup/selfhost.globalsetup.ts
• e2e/src/ports.ts
• package.json
• packages/core/api/src/executions/api.ts
• packages/core/api/src/handlers/executions.ts
• packages/core/config/package.json
• packages/core/execution/package.json
• packages/core/execution/src/description.ts
• packages/core/execution/src/engine.ts
• packages/core/execution/src/promise.ts
• packages/core/execution/src/tool-invoker.test.ts
• packages/core/execution/src/tool-invoker.ts
• 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/cloudflare/src/mcp/agent-session-durable-object.ts
• packages/hosts/mcp/src/stdio-integration.test.ts
• packages/kernel/core/package.json
• packages/kernel/runtime-quickjs/package.json
• packages/plugins/desktop-settings/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/mcp/src/sdk/catalog-sync.test.ts
• packages/plugins/mcp/src/sdk/connection.ts
• packages/plugins/mcp/src/sdk/discover.ts
• packages/plugins/mcp/src/sdk/errors.ts
• packages/plugins/mcp/src/sdk/invoke.ts
• packages/plugins/mcp/src/sdk/manifest.ts
• packages/plugins/mcp/src/sdk/plugin.test.ts
• packages/plugins/mcp/src/sdk/plugin.ts
• 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
• packages/react/package.json
• packages/react/src/components/tool-run-panel.tsx
• packages/react/src/plugins/oauth-reconnect.test.ts
• packages/react/src/plugins/oauth-reconnect.ts
• scripts/validate-release-ref.ts
• tests/presets-reachable.test.ts
• tests/release-workflows.test.ts
• tests/tools-cli.test.ts
• turbo.json

This page provides definitions for the core domain vocabulary, codebase-specific jargon, and technical abbreviations used throughout the Executor project.

Core Domain Terms

Integration

An Integration represents an external API surface or tool source (e.g., a specific OpenAPI specification, a GraphQL endpoint, or an MCP server). It defines what tools are available but does not contain user-specific credentials.

• Code Pointers:
  • Integration interface: packages/core/sdk/src/integration.ts87-90
  • IntegrationRow schema: packages/core/sdk/src/core-schema.ts38
  • registerIntegration logic: packages/core/sdk/src/executor.ts89-90

Connection

A Connection is a configured and optionally authenticated instance of an Integration. While an Integration describes the "Petstore API," a Connection represents "My authenticated Petstore account." One Integration can have many Connections.

• Code Pointers:
  • Connection type: packages/core/sdk/src/connection.ts22
  • createConnection method: packages/core/sdk/src/executor.ts25
  • ConnectionAddress format: packages/core/sdk/src/ids.ts71

Tool

A Tool is an individual unit of functionality (an endpoint, a function, or an operation) exposed by a Connection. Tools are invoked by agents to perform actions or fetch data.

• Code Pointers:
  • Tool type definition: packages/core/sdk/src/tool.ts143
  • ToolAddress parsing: packages/core/sdk/src/executor.ts197-214
  • invokeTool implementation: packages/core/execution/src/tool-invoker.ts33

Executor

The Executor is the central interface of the SDK. It manages the lifecycle of integrations, connections, policies, and tool execution. It acts as the bridge between the high-level API and the underlying storage and execution runtimes.

• Code Pointers:
  • Executor interface: packages/core/sdk/src/executor.ts160-170
  • createExecutor factory: packages/core/sdk/src/index.ts142-145

---

Identity and Multi-Tenancy

Executor uses a hierarchical identity model to partition data and enforce access control.

Term	Definition	Code Entity
Tenant	The top-level isolation boundary (e.g., a specific organization or instance).	Tenant packages/core/sdk/src/ids.ts81
Owner	The entity that "owns" a resource, typically user or org.	Owner packages/core/sdk/src/ids.ts76
Subject	The specific ID of the user or organization (e.g., a UUID).	Subject packages/core/sdk/src/ids.ts80

Natural Language to Code Entity Space: Identity

Title: Identity Mapping

Sources: packages/core/sdk/src/ids.ts76-81 packages/core/sdk/src/executor.ts185

---

Execution Concepts

Elicitation

Elicitation is the process where a tool execution pauses to request input from a human. This is used for OAuth flows (requesting a login), manual approvals (security policies), or missing parameters.

• Code Pointers:
  • ElicitationRequest: packages/core/sdk/src/elicitation.ts49
  • ElicitationResponse: packages/core/sdk/src/elicitation.ts46
  • onElicitation handler: packages/core/sdk/src/executor.ts169-170

Policy

A Policy determines the execution rules for a tool. A tool can be allow (run immediately), approve (require elicitation), or deny (blocked).

• Code Pointers:
  • ToolPolicyRow: packages/core/sdk/src/core-schema.ts42
  • resolveEffectivePolicy: packages/core/sdk/src/policies.ts101

Tool Address

A canonical string used to identify a tool across the system. It follows the pattern: tools.<integration>.<owner>.<connection>.<toolName>.

• Code Pointers:
  • parseToolAddress: packages/core/sdk/src/executor.ts197-214
  • ADDRESS_PREFIX: packages/core/sdk/src/executor.ts176

---

System Architecture Components

Plugin

A Plugin extends the Executor with new source types (OpenAPI, MCP, etc.) or storage capabilities.

• Code Pointers:
  • definePlugin: packages/core/sdk/src/plugin.ts12
  • PluginCtx: packages/core/sdk/src/plugin.ts117

Sidecar

In the Desktop application, the Sidecar is a background process (the CLI daemon) supervised by the Electron main process. It provides the core API and execution environment.

• Code Pointers:
  • DESKTOP_SIDECAR_READY_SENTINEL: apps/cli/src/main.ts190
  • Sidecar bundling: apps/desktop/package.json156-157

MCP (Model Context Protocol)

A protocol used to expose the Executor's tool catalog to AI agents (like Claude or Cursor). Executor acts as an MCP Server to agents and an MCP Client to upstream MCP integrations.

• Code Pointers:
  • mcpPlugin: packages/plugins/mcp/src/sdk/plugin.ts69
  • invokeMcpTool: packages/plugins/mcp/src/sdk/invoke.ts50

Tool Invocation Flow

Title: From Agent Call to Tool Execution

Sources: packages/core/sdk/src/executor.ts160-170 packages/core/execution/src/engine.ts20-40 packages/plugins/mcp/src/sdk/invoke.ts50

---

Technical Abbreviations

• FumaDB: The internal database abstraction layer (ORM-like) used to support multiple adapters (SQLite, PostgreSQL, Memory).
  • fumadb import: packages/core/sdk/src/executor.ts3
• QuickJS: A small, embeddable Javascript engine used as a sandboxed runtime for executing dynamic tool logic.
  • runtime-quickjs package: packages/kernel/runtime-quickjs/package.json2
• XDG: Refers to the XDG Base Directory Specification used by the CLI to determine where to store config and data on Linux/macOS.
  • resolveExecutorDataDir: apps/cli/src/main.ts141

Sources: packages/core/sdk/src/executor.ts apps/cli/src/main.ts packages/core/sdk/src/ids.ts packages/core/sdk/src/elicitation.ts packages/plugins/mcp/src/sdk/plugin.ts