### Install Dependencies and Start Dev Server

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Use these commands to install project dependencies and start the local development server. The server will be available at http://127.0.0.1:4788.

```bash
bun install
bun dev
```

--------------------------------

### Create Executor and List Tools

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/sdk/README.md

Quick start example demonstrating how to create an executor with an 'accept-all' elicitation handler and list available tools. This sets up the basic executor instance.

```typescript
import { createExecutor } from "@executor-js/sdk";

const executor = await createExecutor({
  // Required: how to respond when a tool requests user input mid-call.
  // \"accept-all\" auto-approves every prompt — fine for tests/automation.
  // For an interactive host, pass a handler `(ctx) => Promise<ElicitationResponse>`.
  onElicitation: "accept-all",
});

const tools = await executor.tools.list();
console.log(`scope=${executor.scopes[0]!.id} tools=${tools.length}`);

await executor.close();
```

--------------------------------

### Start Executor Service

Source: https://github.com/rhyssullivan/executor/blob/main/apps/docs/local/cli.mdx

Install and start the durable background service, or run a throwaway foreground runtime.

```bash
executor install   # install/start the durable background service
executor web        # open the web UI at http://127.0.0.1:17888
```

```bash
executor web --foreground
```

--------------------------------

### Install @executor-js/sdk and @executor-js/plugin-mcp

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/mcp/README.md

Install the necessary packages using bun or npm.

```sh
bun add @executor-js/sdk @executor-js/plugin-mcp
# or
npm install @executor-js/sdk @executor-js/plugin-mcp
```

--------------------------------

### Install @executor-js/runtime-quickjs

Source: https://github.com/rhyssullivan/executor/blob/main/packages/kernel/runtime-quickjs/README.md

Install the necessary packages for using the QuickJS runtime with @executor-js.

```sh
bun add @executor-js/execution @executor-js/runtime-quickjs
# or
npm install @executor-js/execution @executor-js/runtime-quickjs
```

--------------------------------

### Install the plugin

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/onepassword/README.md

Install the necessary packages for the executor SDK and the 1Password plugin using either bun or npm.

```sh
bun add @executor-js/sdk @executor-js/plugin-onepassword
# or
npm install @executor-js/sdk @executor-js/plugin-onepassword
```

--------------------------------

### AI Agent Setup Prompt for Executor

Source: https://github.com/rhyssullivan/executor/blob/main/apps/docs/index.mdx

This prompt can be given to AI agents like Claude or Cursor to help set up Executor. It guides the user through choosing a deployment method, installing Executor, connecting it via MCP, and configuring the first integration.

```text
Setup prompt
Help me set up Executor and get my first connection working.

Executor is an open source integration layer for AI agents: one place to configure every integration (MCP servers, OpenAPI specs, GraphQL APIs) and connect to them over MCP.

Start by helping me pick the right form to run it in. Chat with me about it rather than jumping straight to a yes/no question, and recommend one. If I just want the fastest path, suggest Executor Cloud (free tier, nothing to install). All forms expose the same functionality, just packaged differently:

Local (everything stays on my machine):
- Desktop app: a native app for Mac, Windows, and Linux. Best for a regular desktop environment.
- CLI (`executor`): best for a headless or server environment.
Both run a local HTTP server as a background service that any MCP client can connect to.

Hosted (use it from multiple agents, including cloud ones, with nothing running locally):
- Executor Cloud: hosted, generous free tier, sign in and start immediately.
- Self-hosted: a Docker image or a Cloudflare Worker.

How to think about it:
- Want all your data on your own machine? Go local: the desktop app for a regular environment, the CLI for a headless one.
- Want to use it from multiple agents (including cloud agents like ChatGPT), or not run anything locally? Go hosted: Executor Cloud is the fastest start; the self-hosted Docker or Cloudflare versions give you full control.

Terms you'll come across:
- Integration: anything you add (an MCP server, an OpenAPI spec, a GraphQL API).
- Connection: one configured instance of an integration. An integration can have many connections, and a connection doesn't have to be authenticated.
- Policy: whether each tool is always allowed, requires approval, or is blocked. Policies start from a sensible default derived from the imported spec (for example, GET requests on an OpenAPI spec are allowed by default).

Once you know which form I want:
1. Walk me through installing it.
2. Connect Executor to you over MCP. Most MCP clients only load servers at startup, so after adding it I may need to restart the client or open a new chat before the Executor tools appear. Tell me if that's needed and wait for me to do it before continuing.
3. Once the tools are available, help me add my first integration and get one tool working end to end.

Docs: https://executor.sh/docs
Source (and the place to start if something breaks): https://github.com/RhysSullivan/executor
```

--------------------------------

### Install @executor-js/plugin-keychain

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/keychain/README.md

Install the plugin and the SDK using your preferred package manager.

```sh
bun add @executor-js/sdk @executor-js/plugin-keychain
# or
npm install @executor-js/sdk @executor-js/plugin-keychain
```

--------------------------------

### Install and Run Executor

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Installs the Executor CLI globally, sets up the local background service, and opens the web UI for managing tools and sources.

```bash
npm install -g executor
executor install
executor web
```

--------------------------------

### Install Executor SDK

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/sdk/README.md

Install the @executor-js/sdk using npm or bun. This is the first step to using the SDK in your project.

```sh
bun add @executor-js/sdk
# or
npm install @executor-js/sdk
```

--------------------------------

### Install OpenAPI Plugin

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/openapi/README.md

Install the necessary packages for the OpenAPI plugin using bun or npm.

```sh
bun add @executor-js/sdk @executor-js/plugin-openapi
# or
npm install @executor-js/sdk @executor-js/plugin-openapi
```

--------------------------------

### Install @executor-js/plugin-file-secrets

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/file-secrets/README.md

Install the SDK and the file secrets plugin using bun or npm.

```sh
bun add @executor-js/sdk @executor-js/plugin-file-secrets
# or
npm install @executor-js/sdk @executor-js/plugin-file-secrets
```

--------------------------------

### Start Development Servers (Monorepo)

Source: https://github.com/rhyssullivan/executor/blob/main/RUNNING.md

Use this command from the repository root to start development servers for all applications except desktop and cloud. This utilizes Turbo for efficient development builds.

```bash
bun run dev
```

--------------------------------

### Install and Manage Executor Background Service

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Commands to install, start, stop, and check the status of the persistent Executor background service and its associated daemon.

```bash
executor install                    # install/start the durable background service
executor web                        # open the running web UI
executor web --foreground           # start a temporary foreground runtime + web UI
executor daemon run                 # start persistent local daemon in background
executor daemon status              # show daemon status
executor daemon stop                # stop daemon
executor daemon restart             # restart daemon
executor mcp                        # start MCP endpoint
```

--------------------------------

### Install Executor.js Packages

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/execution/README.md

Install the necessary Executor.js packages using either Bun or npm. Ensure you include the SDK, execution engine, and a runtime like QuickJS.

```sh
bun add @executor-js/sdk @executor-js/execution @executor-js/runtime-quickjs
# or
npm install @executor-js/sdk @executor-js/execution @executor-js/runtime-quickjs
```

--------------------------------

### Install @executor-js/plugin-graphql

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/graphql/README.md

Install the necessary packages for the executor SDK and the GraphQL plugin using bun or npm.

```sh
bun add @executor-js/sdk @executor-js/plugin-graphql
# or
npm install @executor-js/sdk @executor-js/plugin-graphql
```

--------------------------------

### Deploy Executor Worker Setup

Source: https://github.com/rhyssullivan/executor/blob/main/apps/docs/hosted/cloudflare.mdx

Run the setup script to initialize the D1 database, configure Wrangler, and upload secrets for the Cloudflare Worker deployment.

```bash
bunx wrangler login
bun run deploy:setup
```

--------------------------------

### Start Beta Release Mode

Source: https://github.com/rhyssullivan/executor/blob/main/RELEASING.md

Initiate prerelease mode to start a beta release train. This commits the pre.json file and affects future versioning.

```bash
bun run release:beta:start
```

--------------------------------

### Manual mapping example

Source: https://github.com/rhyssullivan/executor/blob/main/notes/openapi-sdk-credential-configuration.md

This example shows manual mappings that the OpenAPI SDK should derive automatically from the source shape, avoiding the need for users to specify them.

```txt
Authorization -> header:authorization
OAuth client ID -> oauth2:<scheme>:client-id
OAuth connection -> oauth2:<scheme>:connection
```

--------------------------------

### Graphql Configure Form Example

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

A React component example for configuring GraphQL credentials, utilizing shared UI sections for HTTP credentials.

```tsx
<GraphqlConfigureForm>
  <HttpCredentials.Section field="request" title="Request" />
</GraphqlConfigureForm>
```

--------------------------------

### Install Executor CLI

Source: https://github.com/rhyssullivan/executor/blob/main/apps/docs/local/cli.mdx

Install the Executor CLI globally using npm, pnpm, bun, or yarn. Requires Node.js 20 or newer.

```bash
npm install -g executor
```

```bash
pnpm add -g executor
```

```bash
bun add -g executor
```

```bash
yarn global add executor
```

--------------------------------

### Install @executor-js/codemode-core

Source: https://github.com/rhyssullivan/executor/blob/main/packages/kernel/core/README.md

Install the core package using your preferred package manager.

```sh
bun add @executor-js/codemode-core
```

```sh
npm install @executor-js/codemode-core
```

--------------------------------

### Install Playwright Chromium

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Install the necessary browser binary for running end-to-end tests in the browser.

```bash
bunx playwright install chromium
```

--------------------------------

### Develop Executor Docs Locally

Source: https://github.com/rhyssullivan/executor/blob/main/apps/docs/README.md

Run the Mintlify CLI to start a local development server for the documentation. Use the broken-links command to validate internal links.

```bash
bunx mint@latest dev            # http://localhost:3000
bunx mint@latest broken-links   # validate internal links
```

--------------------------------

### URI Proxying Examples

Source: https://github.com/rhyssullivan/executor/blob/main/notes/mcp-apps-executor-gateway.md

Examples illustrating how downstream resource URIs are prefixed by Executor for gateway access and how this prefix is stripped when forwarding requests to the source MCP server. This ensures unique URIs within the gateway.

```text
downstream: ui://app/show_github_issue.html
executor:   executor+mcp://{sourceId}/ui/app/show_github_issue.html
```

```text
downstream: ui://app/show_github_issue.html
executor:   ui://executor/{sourceId}/app/show_github_issue.html
```

--------------------------------

### Create Astro Project with Minimal Template

Source: https://github.com/rhyssullivan/executor/blob/main/apps/marketing/README.md

Use this command to initialize a new Astro project using the minimal template. Ensure you have Node.js installed.

```sh
npm create astro@latest -- --template minimal
```

--------------------------------

### MCP Http Configure Form Example

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

A React component example for configuring MCP HTTP credentials, using shared UI sections for HTTP credentials.

```tsx
<McpHttpConfigureForm>
  <HttpCredentials.Section field="request" title="Request" />
</McpHttpConfigureForm>
```

--------------------------------

### UI Context Switcher Display

Source: https://github.com/rhyssullivan/executor/blob/main/notes/cloud-workspaces-and-global-sources-plan.md

Example of how global and workspace contexts are displayed in the UI context switcher.

```txt
Acme / Global
Acme / Billing API
```

--------------------------------

### Search and Describe Tools via CLI

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Search for tools based on intent or get detailed schema information for a specific tool path.

```bash
executor tools search "<query>"     # search tools by intent
executor tools sources              # list configured sources + tool counts
executor tools describe <path>      # show tool TypeScript/JSON schema
```

--------------------------------

### Get Initial Records

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/fumadb/test/query/relations.output.txt

Retrieving initial posts associated with the created users.

```json
[
  {
    attachmentUrl: null,
    authorId: 'fuma',
    content: 'hello world',
    id: '1',
    relyTo: null
  },
  {
    attachmentUrl: 'attachment-1',
    authorId: 'joulev',
    content: 'default content.',
    id: '2',
    relyTo: '1'
  },
  {
    attachmentUrl: null,
    authorId: 'alfon',
    content: 'hehe',
    id: '3',
    relyTo: null
  }
]
```

--------------------------------

### Install Executor MCP Bridge for Pi

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Installs the community-developed bridge to enable Pi to interact with Executor's tool catalog.

```bash
pi install git:github.com/gvkhosla/pi-executor-mcp@v0.2.0
```

--------------------------------

### Bootstrap Project Dependencies

Source: https://github.com/rhyssullivan/executor/blob/main/RUNNING.md

Run this command from the repository root to install dependencies and build necessary artifacts. It is idempotent and ensures all required packages, including Vite plugin and React artifacts, are prepared.

```bash
bun run bootstrap
```

--------------------------------

### Executor Composition Example

Source: https://github.com/rhyssullivan/executor/blob/main/notes/artifacts-workflows-and-generated-ui.md

Demonstrates how to compose an Executor instance with various plugins, including the local Git artifact provider and the workflows plugin. It also shows how to create a new workflow.

```typescript
const executor =
  yield * 
  createExecutor({
    scopes: [userScope],
    adapter,
    blobs,
    plugins: [
      artifactsLocalGitPlugin({ rootDir: ".executor-artifacts" }),
      workflowsPlugin(),
    ] as const,
    protocols: {
      "executor.artifacts.store": "artifacts-local-git",
    },
  });

const workflow =
  yield * 
  executor.workflows.create({
    name: "Support triage",
    files: [
      {
        type: "put",
        path: "artifact.json",
        contents: JSON.stringify({
          schemaVersion: 1,
          kind: "workflow",
          entrypoints: ["src/workflows/support-triage.workflow.ts"],
        }),
      },
      {
        type: "put",
        path: "src/workflows/support-triage.workflow.ts",
        contents: supportTriageWorkflowSource,
      },
      {
        type: "put",
        path: "src/steps/summarize.ts",
        contents: summarizeStepSource,
      },
    ],
  });
```

--------------------------------

### Configure 1Password with Desktop App

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/onepassword/README.md

Initialize the executor with the 1Password plugin and configure it to use the desktop app for authentication. This example also shows how to inspect connection status and list available vaults.

```ts
import { createExecutor } from "@executor-js/sdk";
import { onepasswordPlugin } from "@executor-js/plugin-onepassword";

const executor = await createExecutor({
  onElicitation: "accept-all",
  plugins: [onepasswordPlugin()] as const,
});

// Point the plugin at your account
await executor.onepassword.configure({
  auth: { kind: "desktop-app", accountName: "my-account" },
  vaultId: "my-vault-id",
  name: "Personal",
});

// Inspect connection / list vaults
const status = await executor.onepassword.status();
const vaults = await executor.onepassword.listVaults({
  kind: "desktop-app",
  accountName: "my-account",
});
```

--------------------------------

### Example Credential Binding Value

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

Shows a specific credential binding for an OpenAPI source, linking a slot key to a secret.

```txt
credential_binding
  plugin_id = "openapi"
  source_id = "stripe"
  source_scope_id = "org_acme"
  scope_id = "user_rhys"
  slot_key = "request.headers.authorization"
  kind = "secret"
  secret_id = "stripe_api_key"
```

--------------------------------

### Run E2E Desk Scenario

Source: https://github.com/rhyssullivan/executor/blob/main/e2e/AGENTS.md

Executes an end-to-end scenario using Docker. The first run will build and install necessary dependencies. Set E2E_DESK=1 to switch transports for desk recordings.

```bash
e2e/desk/run.sh [scenario] [project]
```

--------------------------------

### Plugin File Structure Example

Source: https://github.com/rhyssullivan/executor/blob/main/notes/dynamic-plugin-loading-v1.md

Illustrates a typical file structure for a plugin package, separating server-side logic, client-side components, and shared types. This organization ensures strict separation between server and client bundles.

```plaintext
@executor-js/plugin-foo/
├── package.json
├── src/
│   ├── server.ts    # Effect, Node deps, definePlugin
│   ├── client.tsx   # React, defineClientPlugin
│   └── shared.ts    # Schemas, types shared across the boundary
└── dist/

```

--------------------------------

### Example Plugin Server Implementation

Source: https://github.com/rhyssullivan/executor/blob/main/notes/dynamic-plugin-loading-v1.md

Implements the server-side logic for a plugin, defining its API bundle, extension service, and handlers. The handlers use late-binding to access the extension service.

```typescript
// @executor-js/plugin-foo/src/server.ts
import {
  Context, definePlugin, Effect, HttpApi,
  HttpApiBuilder,
} from "@executor-js/sdk"
import { FooApi } from "./shared"

// Bundle the group into a small HttpApi *for typing purposes only*. The
// handlers Layer is keyed by the FooApi group's identity, so it composes
// cleanly into the host's FullApi at runtime regardless of what other
// groups are around it.
const FooApiBundle = HttpApi.make("foo").add(FooApi)

interface FooExtension {
  readonly listThings: () => Effect.Effect<readonly Thing[]>
  readonly syncThing: (id: string) => Effect.Effect<Thing>
}

// Service tag for late-binding — the host satisfies this at boot
// (local) or per request (cloud). Same pattern as the established
// `*ExtensionService` in each plugin's `*/api/handlers.ts`.
export class FooExtensionService extends Context.Service<
  FooExtensionService, FooExtension,
>()("FooExtensionService") {}

const FooHandlers = HttpApiBuilder.group(FooApiBundle, "foo", (h) =>
  h
    .handle("listThings", () =>
      Effect.gen(function* () {
        const ext = yield* FooExtensionService
        return yield* ext.listThings()
      }),
    )
    .handle("syncThing", ({ path }) =>
      Effect.gen(function* () {

```

--------------------------------

### Example OpenAPI Source Configuration with Credential Slots

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

Illustrates an OpenAPI source configuration that declares credential slots for authorization headers and spec fetching.

```ts
{
  request: {
    headers: {
      Authorization: {
        slotKey: "request.headers.authorization",
        prefix: "Bearer ",
      },
    },
    query: {},
  },
  specFetch: {
    headers: {},
    query: {},
  },
}
```

--------------------------------

### In-Process Worker Fetch Example

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/test-servers/README.md

Demonstrates how to fetch from the in-process Worker export for testing purposes. This is the method used by the local test fixture.

```ts
import worker from "@executor-js/test-servers";

const response = await worker.fetch(new Request("https://example.test/health"));
```

--------------------------------

### Get Execution Workflow Description

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/execution/README.md

Retrieve a description of the recommended workflow for LLMs to interact with the sandbox. This includes instructions on how to use tools like `tools.search` and `tools.describe.tool`.

```ts
import type { ExecutionEngine } from "@executor-js/execution";

declare const engine: ExecutionEngine;

const docs = await engine.getDescription();
// Returns the canonical "use tools.search(), then tools.describe.tool(), then call …"
// workflow prose + per-namespace tool listing. Feed this to an LLM so it knows
// how to drive the sandbox.
```

--------------------------------

### Vitest Command for Test Execution

Source: https://github.com/rhyssullivan/executor/blob/main/notes/livestore-effect-testing-porting.md

Example command for running specific Vitest tests, useful for targeted validation during the porting process. This helps in verifying individual test conversions.

```bash
vitest run <converted test file> --testNamePattern "<converted test>"
```

--------------------------------

### MCP Server Configuration for Claude Code / Cursor

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Example JSON configuration for agents like Claude Code or Cursor to connect to an Executor MCP server.

```json
{
  "mcpServers": {
    "executor": {
      "command": "executor",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### MCP Plugin HTTP Helper

Source: https://github.com/rhyssullivan/executor/blob/main/notes/real-protocol-testing-plan.md

Starts a real node HTTP server, creates McpServer instances, and routes StreamableHTTPServerTransport sessions. This helper is intended to become a public testing export.

```typescript
It starts a real node HTTP server,
creates `McpServer` instances, and routes `StreamableHTTPServerTransport`
sessions with `mcp-session-id`.
That should become a plugin-owned testing
export rather than staying as private test utility code.
```

--------------------------------

### Example Executor Plugin Manifest

Source: https://github.com/rhyssullivan/executor/blob/main/notes/research/plugins/manifest-schema.md

This JSON object illustrates a sample Executor plugin manifest, including schema version, ID, name, compatibility, entrypoints, extensions, and capabilities like network access and storage.

```json
{
  "schemaVersion": "0.1",
  "id": "@executor/openapi",
  "name": "OpenAPI",
  "version": "0.1.0",
  "description": "Create Executor sources and tools from OpenAPI specs.",
  "compatibility": {
    "executor": ">=0.1.0",
    "runtimeApi": "0.1",
    "platforms": ["local", "cloud"]
  },
  "entrypoints": {
    "source": {
      "module": "./dist/source.js",
      "export": "default",
      "runtime": "worker"
    }
  },
  "extensions": {
    "sources": [
      {
        "kind": "openapi",
        "displayName": "OpenAPI"
      }
    ]
  },
  "capabilities": {
    "network": [
      {
        "hosts": ["*"]
      }
    ],
    "storage": [
      {
        "collection": "sources"
      }
    ]
  }
}
```

--------------------------------

### List Configured Integrations

Source: https://github.com/rhyssullivan/executor/blob/main/apps/docs/local/cli.mdx

Confirm that integrations have been added and are live by listing configured sources.

```bash
executor tools sources   # lists configured integrations + tool counts
```

--------------------------------

### Plugin Install Specification Type

Source: https://github.com/rhyssullivan/executor/blob/main/notes/research/plugins/manifest-schema.md

Defines the type for plugin installation specifications, which can be a string or a tuple containing a string and configuration options.

```typescript
type PluginInstallSpec = string | [string, Record<string, unknown>];
```

--------------------------------

### Basic Execution with Tools

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/execution/README.md

Execute JavaScript code within a sandbox that has access to registered tools via the `tools` proxy. This example demonstrates fetching pet data and returning the count. It also shows how to handle elicitation requests from tools.

```ts
import { createExecutor } from "@executor-js/sdk";
import { createExecutionEngine } from "@executor-js/execution";
import { makeQuickJsExecutor } from "@executor-js/runtime-quickjs";

const executor = await createExecutor({
  onElicitation: "accept-all",
});

const engine = createExecutionEngine({
  executor,
  codeExecutor: makeQuickJsExecutor({
    timeoutMs: 2_000,
    memoryLimitBytes: 32 * 1024 * 1024,
  }),
});

const result = await engine.execute(
  `
    const pets = await tools.petstore.findPetsByStatus({ status: "available" });
    return pets.length;
  `,
  {
    onElicitation: async (ctx) => {
      // A tool asked for user input mid-execution. Your UI decides what to do.
      console.log("tool needs input:", ctx.request);
      return { action: "decline" };
    },
  },
);

console.log(result);
// { result: 12, logs: [...] }
```

--------------------------------

### Generated Workflow Code Example

Source: https://github.com/rhyssullivan/executor/blob/main/notes/artifacts-workflows-and-generated-ui.md

An example of a generated workflow function written in TypeScript. This workflow processes input, generates a summary, and conditionally creates a Linear issue.

```typescript
// src/workflows/support-triage.workflow.ts
import { createLinearIssue } from "../steps/linear";
import { summarizeTicket } from "../steps/summarize";

export async function supportTriage(input: SupportEmail) {
  "use workflow";

  const summary = await summarizeTicket(input);

  if (summary.priority === "high") {
    return await createLinearIssue({
      title: summary.title,
      body: summary.body,
    });
  }

  return { status: "ignored", summary };
}
```

--------------------------------

### Host App Root Component Setup

Source: https://github.com/rhyssullivan/executor/blob/main/notes/dynamic-plugin-loading-v1.md

The host application's root component uses `ExecutorPluginsProvider` to make client-side plugins available to the application. This setup should be at the root of your application's routing.

```tsx
// apps/local/src/routes/__root.tsx
import { createRootRoute } from "@tanstack/react-router";
import { ExecutorProvider } from "@executor-js/react/api/provider";
import { ExecutorPluginsProvider } from "@executor-js/sdk/client";
import { plugins as clientPlugins } from "virtual:executor/plugins-client";
import { Shell } from "../web/shell";

export const Route = createRootRoute({
  component: () => (
    <ExecutorProvider>
      <ExecutorPluginsProvider plugins={clientPlugins}>
        <Shell />
      </ExecutorPluginsProvider>
    </ExecutorProvider>
  ),
});

```

--------------------------------

### Initialize Executor with Keychain Plugin

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/keychain/README.md

Create an executor instance and include the keychain plugin. Check if the OS keychain is supported before using secret operations.

```ts
import { createExecutor } from "@executor-js/sdk";
import { keychainPlugin } from "@executor-js/plugin-keychain";

const executor = await createExecutor({
  onElicitation: "accept-all",
  plugins: [keychainPlugin()] as const,
});

// Check whether the current OS has a supported keychain
if (executor.keychain.isSupported) {
  await executor.secrets.set({
    id: "github-token",
    name: "GitHub Token",
    value: "ghp_...",
    scope: executor.scopes[0]!.id,
  });

  const value = await executor.secrets.get("github-token");
}
```

--------------------------------

### Get 1Password Status

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/onepassword/README.md

Retrieves the current status of the 1Password connection.

```APIDOC
## status

### Description
Retrieves the current status of the 1Password connection.

### Method
`executor.onepassword.status()`

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - The current status of the 1Password connection.
```

--------------------------------

### GraphQL HTTP Configuration Input

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

Example of how GraphQL embeds the HTTP request configuration once.

```typescript
type GraphqlConfigureInput = {
  type: "graphql";
  scope: ScopeId;
  request?: HttpRequestConfigureInput;
};
```

--------------------------------

### Deterministic Scope ID Prefixes

Source: https://github.com/rhyssullivan/executor/blob/main/notes/cloud-workspaces-and-global-sources-plan.md

Examples of deterministic and prefixed scope IDs for various entities.

```txt
org_<orgId>
workspace_<workspaceId>
user_org_<userId>_<orgId>
user_workspace_<userId>_<workspaceId>
```

--------------------------------

### Verify Executor Bridge Status in Pi

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Commands to reload Pi and check the status of the Executor bridge after installation.

```text
/reload
/executor-status
```

--------------------------------

### Error Message for Unknown Header

Source: https://github.com/rhyssullivan/executor/blob/main/notes/openapi-sdk-credential-configuration.md

Example of the suggested error message when an unknown header is provided during OpenAPI configuration.

```text
Unknown header "Username" for OpenAPI source "stripe".
Declared headers: Authorization.
```

--------------------------------

### Executor Construction with Custom Plugin Storage

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

Demonstrates how to provide a custom plugin storage provider during Executor construction.

```ts
createExecutor({
  pluginStorage: myPluginStorageProvider,
});
```

--------------------------------

### Search and Call Tools via CLI

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Utilize the CLI to search for tools by intent, view help for commands, and directly call tool methods with arguments, including JSON payloads.

```bash
executor tools search "send email"
executor call --help
executor call github --help
executor call github issues --help
executor call cloudflare --help --match dns --limit 20
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
executor call gmail send '{"to":"alice@example.com","subject":"Hi"}'
```

--------------------------------

### Workspace ID Generation Pattern

Source: https://github.com/rhyssullivan/executor/blob/main/notes/cloud-workspaces-and-global-sources-plan.md

Example of a prefixed random ID format for new local entities like workspaces.

```txt
workspace_<base58 random>
```

--------------------------------

### Import Keychain Plugin for Effect Usage

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/keychain/README.md

When building on `@executor-js/sdk/core`, import the plugin from its `/core` subpath to get the Effect-shaped plugin.

```ts
import { keychainPlugin } from "@executor-js/plugin-keychain/core";
```

--------------------------------

### OpenAPI HTTP Configuration Input

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

Example of how OpenAPI can embed the HTTP request configuration twice for different purposes (request and specFetch).

```typescript
type OpenApiConfigureInput = {
  type: "openapi";
  scope: ScopeId;
  request?: HttpRequestConfigureInput;
  specFetch?: HttpRequestConfigureInput;
};
```

--------------------------------

### Invoke Tools and Browse Namespaces via CLI

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Invoke tools by specifying their path segments and providing arguments, or browse available namespaces, resources, and methods using the `--help` flag.

```bash
executor call <path...> '{"k":"v"}' # invoke a tool by path segments
executor call <path...> --help      # browse namespaces/resources/methods
executor call <path...> --help --match "<text>" --limit <n> # narrow huge namespaces
```

--------------------------------

### Programmatic Consumption of SDK-only Plugin

Source: https://github.com/rhyssullivan/executor/blob/main/notes/dynamic-plugin-loading-v1.md

Examples of how to consume an SDK-only plugin like the rate limiter directly from code, such as in tests or other plugins.

```typescript
const result = yield * executor.rateLimiter.check("user-123", 5);
//    ^? { allowed: true; remaining: number }

yield *
  executor.rateLimiter
    .check("user-123", 1000)
    .pipe(
      Effect.catchTag("RateLimitExceeded", (err) =>
        Effect.log(`hit limit on ${err.key}, retry in ${err.retryAfterMs}ms`),
      ),
    );
```

--------------------------------

### OpenAPI Configuration with Various Value Types

Source: https://github.com/rhyssullivan/executor/blob/main/notes/openapi-sdk-credential-configuration.md

An example of configuring OpenAPI credentials using different accepted value types: SecretId and string.

```typescript
await executor.openapi.configure(source, {
  scope: user,
  headers: {
    Authorization: SecretId.make("stripe_api_key"),
    "X-Workspace": "acme",
  },
  queryParams: {
    version: "2026-05-17",
  },
});
```

--------------------------------

### Source Shape Header Configuration

Source: https://github.com/rhyssullivan/executor/blob/main/notes/openapi-add-source-api-cleanup.md

Example of configuring a shared `Authorization` header with a bearer prefix. The concrete token value is supplied separately.

```ts
headers: {
  Authorization: {
    kind: "secret",
    prefix: "Bearer ",
  },
},
queryParams: {
  api_version: "2026-05-17",
}
```

--------------------------------

### Plugin Instantiation with Custom Storage

Source: https://github.com/rhyssullivan/executor/blob/main/notes/plugin-source-configuration-overhaul.md

Shows an alternative pattern for providing custom plugin storage when instantiating a specific plugin, like the OpenAPI plugin.

```ts
openApiPlugin({
  storage: myPluginStorageProvider,
});
```

--------------------------------

### Build and Run Self-hosted Executor with Docker Compose

Source: https://github.com/rhyssullivan/executor/blob/main/apps/host-selfhost/README.md

Build the Docker image from a repository clone and run the self-hosted Executor server using Docker Compose. After starting, access the UI at http://localhost:4788 to create the admin account.

```bash
# From this directory:
docker compose up -d --build
# then open http://localhost:4788 and create the admin account
```

--------------------------------

### Create Initial Messages

Source: https://github.com/rhyssullivan/executor/blob/main/packages/core/fumadb/test/query/query.output.txt

Creates two initial messages, demonstrating content, user association, and mention relationships.

```javascript
[
  {
    content: 'Hello World 1 by alfon',
    id: '1',
    image: null,
    mentionId: null,
    parent: null,
    user: 'alfon'
  },
  {
    content: 'Hello World 2 by alfon',
    id: '2',
    image: null,
    mentionId: '1',
    parent: null,
    user: 'alfon'
  }
]
```

--------------------------------

### Initialize Executor with MCP Plugin

Source: https://github.com/rhyssullivan/executor/blob/main/packages/plugins/mcp/README.md

Create an executor instance and configure it to use the MCP plugin. Ensure to set `dangerouslyAllowStdioMCP` to true if you intend to use stdio-launched MCP servers.

```ts
import { createExecutor } from "@executor-js/sdk";
import { mcpPlugin } from "@executor-js/plugin-mcp";

const executor = await createExecutor({
  onElicitation: "accept-all",
  // Stdio sources spawn a local subprocess and inherit `process.env` —
  // only enable for trusted single-user contexts.
  plugins: [mcpPlugin({ dangerouslyAllowStdioMCP: true })] as const,
});
```

--------------------------------

### Run Executor as an MCP Server

Source: https://github.com/rhyssullivan/executor/blob/main/README.md

Starts the Executor background service to act as an MCP server, allowing compatible agents to access its tool catalog.

```bash
executor mcp
```