executor-pi

executor-pi is a first-class Pi extension for running Executor from inside Pi with native approval, elicitation, rendering, and project-aware Executor configuration.

It is not a generic MCP adapter. Pi exposes a small Executor-specific surface, while Executor remains responsible for tools, sources, secrets, policies, plugins, and execution semantics.

Features

Executor-Native Execution

• Run Executor TypeScript snippets directly from Pi.
• Use Executor SDK semantics instead of shelling out to a daemon.
• Keep two primary tools: search for discovery and execute for execution.
• Use the active project cwd as the Executor scope.

Local Executor Config Semantics

• Load Executor's static plugin defaults.
• Load project-level executor.jsonc.
• Preserve Executor plugin merge behavior.
• Use stable cwd-derived scope IDs.
• Reuse local Executor storage semantics.

Pi-Native Elicitation

• Render approval prompts as Pi confirmations.
• Render form elicitation as Pi form UI or a structured editor fallback.
• Render URL elicitation with clear domain and action context.
• Treat accept, decline, and cancel as explicit outcomes.
• Fail loudly for unsupported elicitation shapes.

Rich Rendering

• Syntax-highlight Executor code before execution.
• Render Executor search results with paths, descriptions, and pagination hints.
• Render structured JSON cleanly.
• Separate summaries, logs, errors, and outputs.
• Show paused or elicitation states clearly.
• Keep large results readable inside Pi.

Commands And Guidance

• Provide /executor status and diagnostics.
• Add focused settings and help commands for Executor workflows.
• Include Executor usage guidance directly in the search and execute tool prompts.
• Avoid generic MCP search, describe, and invoke tool sprawl.

Architecture

flowchart TB
  Pi["Pi ExtensionAPI"] --> Runtime["Effect ManagedRuntime"]
  Runtime --> Tools["Pi search + execute tools"]
  Runtime --> Commands["/executor commands"]
  Runtime --> UX["Pi elicitation UI"]
  Runtime --> Host["ExecutorHostService"]

  Host --> LocalHost["Executor local host"]
  LocalHost --> SDK["Executor SDK"]
  LocalHost --> Engine["Execution Engine + QuickJS"]
  LocalHost --> Config["static plugins + executor.jsonc"]
  LocalHost --> Storage["~/.executor storage"]

  SDK --> Sources["Executor sources/plugins/secrets"]
  Engine --> UX

Pi owns the interaction surface. Executor owns execution, configuration, tools, sources, secrets, and policy.

Usage

Install the extension into Pi, then use the Executor tool from a project with the desired executor.jsonc configuration.

await tools.search({
  query: "github issues",
  includeDetails: true,
});

await tools.execute({
  code: `
    const { items } = await tools.search({ query: "github issues", limit: 5 });
    return items;
  `,
});

Use /executor inside Pi to inspect extension status, active scope, loaded configuration, and available diagnostics.

Configuration

executor-pi follows Executor's local project configuration model:

• Project config: executor.jsonc in the active project.
• Storage: local Executor storage under ~/.executor.
• Scope: derived from the active project cwd.
• Plugins: Executor defaults merged with project plugins.

Pi-specific settings only control the Pi extension experience, such as rendering preferences and command behavior. Tool sources, secrets, policies, and plugin configuration stay in Executor.

Pi Executor settings files:

• Global: ~/.pi/agent/executor-pi.json
• Project override: .pi/executor-pi.json

Use /executor config in the Pi TUI to adjust display density (concise, balanced, verbose, or custom), search defaults, and render limits. /executor settings is accepted as an alias for config.

Development

This package uses Bun, Effect v4, tsgo, oxlint, and oxfmt.

bun install
bun run typecheck
bun run lint
bun run format:check
bun run test
bun run verify:host
bun run check

Formatting:

bun run format

The TypeScript config is local to this package. There is no shared tsconfig package.

Effect services use Context.Service, Layer, scoped resources, and typed errors. Pi callbacks are thin Promise adapters around the Effect runtime.

Host contract and local package notes live in:

• docs/executor-host.md
• docs/local-fumadb.md

Non-Goals

• Building a generic MCP adapter for Pi.
• Running Executor's Bun server inside the extension.
• Serving Executor's React web UI from this package.
• Reimplementing Executor sources, plugins, secrets, or policy in Pi.
• Exposing every upstream MCP tool directly to the agent context.