pi-lazy-extensions 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+<div align="center">
+
+# 🦥 pi-lazy-extensions
+
+**Lazy-load [pi](https://github.com/earendil-works/pi-coding-agent) extensions on demand**
+
+_ToolSearch-style proxy tool — extensions only load when you need them._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+---
+
+## The Problem
+
+Every extension in `~/.pi/agent/extensions/` loads at startup. If you have many extensions, they all register their tools, commands, and event handlers immediately — even if you rarely use them. This clutters the tool list and wastes resources.
+
+## The Solution
+
+`pi-lazy-extensions` registers a single `ext` proxy tool. The LLM discovers and activates extensions on demand, just like Anthropic's ToolSearch for MCP tools. Extensions stay unloaded until needed.
+
+```
+Startup: only eager extensions load
+    │
+    ▼
+┌─────────────┐
+│  ext tool   │  ← always available
+│  (pi-lazy)  │
+└──────┬──────┘
+       │
+       │ LLM calls ext({ activate: "todo" })
+       ▼
+┌─────────────┐
+│  todo ext   │  ← loaded on demand
+│  (lazy)     │     tools appear instantly
+└─────────────┘
+```
+
+---
+
+## Install
+
+```bash
+pi install npm:pi-lazy-extensions
+```
+
+---
+
+## Setup
+
+Create a `lazy-extensions.json` manifest in your project root or `.pi/` directory:
+
+```json
+{
+  "version": 1,
+  "extensions": [
+    {
+      "name": "todo",
+      "path": "~/.pi/agent/extensions/todo.ts",
+      "lifecycle": "lazy",
+      "description": "Task management - create, list, and track todos",
+      "toolSummary": ["todo_list", "todo_add", "todo_complete"],
+      "tags": ["productivity", "tasks"]
+    },
+    {
+      "name": "snake",
+      "path": "~/.pi/agent/extensions/snake.ts",
+      "lifecycle": "lazy",
+      "description": "Snake game while you wait",
+      "tags": ["fun"]
+    },
+    {
+      "name": "git-checkpoint",
+      "path": "~/.pi/agent/extensions/git-checkpoint.ts",
+      "lifecycle": "eager",
+      "description": "Auto git stash/restore on each turn"
+    }
+  ],
+  "settings": {
+    "idleTimeout": 10,
+    "eagerOverrides": ""
+  }
+}
+```
+
+### Manifest Location
+
+The manifest is searched in this order:
+
+1. `LAZY_EXTENSIONS_CONFIG` environment variable (explicit path)
+2. `<cwd>/.pi/lazy-extensions.json` (project `.pi` dir)
+3. `~/.pi/agent/lazy-extensions.json` (global)
+4. `<cwd>/lazy-extensions.json` (project root)
+
+### Extension Config
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Unique identifier for the extension |
+| `path` | string | Path to the extension's entry point (`.ts` or `.js`) |
+| `lifecycle` | `"lazy"` \| `"eager"` \| `"keep-alive"` | Default: `"lazy"`. Eager loads at startup, keep-alive never unloads |
+| `description` | string? | What the extension does (shown in search results) |
+| `toolSummary` | string[]? | Names of tools this extension registers (for discovery before load) |
+| `tags` | string[]? | Search/filter tags |
+
+### Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `disableProxyTool` | boolean | false | If true, don't register the `ext` proxy tool |
+| `idleTimeout` | number | 10 | Minutes before unloading idle lazy extensions (0 = never) |
+| `eagerOverrides` | string | "" | Comma-separated extension names to force eager loading |
+
+---
+
+## Usage
+
+### Via the `ext` tool (LLM calls)
+
+```
+ext({})                                    → Status: list all extensions
+ext({ search: "todo" })                   → Search extensions matching "todo"
+ext({ activate: "todo" })                 → Load and activate the "todo" extension
+ext({ tools: "todo" })                    → List tools registered by "todo"
+```
+
+After `ext({ activate: "todo" })`, the `todo` extension's tools become directly available to the LLM.
+
+### Via the `/ext` command (user calls)
+
+```
+/ext                           → Show status
+/ext activate todo             → Activate an extension
+/ext search productivity       → Search extensions
+/ext tools todo                → List extension tools
+```
+
+---
+
+## How It Works
+
+1. At startup, `pi-lazy-extensions` reads the manifest and registers the `ext` proxy tool
+2. **Eager** and **keep-alive** extensions are loaded immediately during `session_start`
+3. **Lazy** extensions stay unloaded — their metadata is available for search/discovery
+4. When the LLM (or user) calls `ext({ activate: "name" })`, the extension is dynamically loaded via jiti (with the same module alias map that pi's own loader uses, so `import { Type } from "typebox"` and `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"` work correctly), and its factory function is called with the shared `ExtensionAPI`
+5. New tools registered by the activated extension appear immediately — no `/reload` needed
+6. After an idle timeout, lazy extensions are "soft unloaded" (their tools are deactivated)
+
+---
+
+### Limitations
+
+- **No full unloading:** Once an extension's factory runs, its event handlers are permanent. Idle unloading only removes tools from the active set.
+- **Shortcuts, flags, and message renderers persist:** These registrations have no deactivate/remove API in the current ExtensionAPI. They remain active even after idle-unload. The `ext` status display shows counts of these for awareness.
+- **`sourceInfo` attribution:** Tools registered by lazy-loaded extensions will show the `pi-lazy-extensions` extension's `sourceInfo`, not the original extension's. This is because `pi.registerTool()` stamps each tool with the `sourceInfo` of the *extension that made the call* — and since the lazy extension's factory receives the same `ExtensionAPI` as `pi-lazy-extensions`, all registered tools are attributed to `pi-lazy-extensions`. There is no SDK API to override this.
+- **`/ext` command vs `ext` tool:** The `/ext` command uses `ctx.ui.notify()` for output, which may truncate large results. For rich output (search results, detailed status), prefer the `ext` tool interface which renders properly in the TUI.
+- **`session_start` handlers never fire for the current session:** When a lazy extension is activated mid-session, any `session_start` handlers it registers will not fire until the next session or `/reload`. Extensions that depend on `session_start` for initialization (reading config, setting up state) may not work correctly when lazy-loaded. The `ext` tool displays a warning when this is detected.
+- **Duplicate tool names:** If a lazy extension registers a tool with the same name as an already-registered tool, pi's "first registration wins" policy silently skips it. The `ext` tool displays a warning when this is detected during activation.
+
+---
+
+## Example: Converting an Existing Extension
+
+Before (always loaded):
+```
+~/.pi/agent/extensions/my-heavy-ext.ts
+```
+
+After (lazy loaded):
+
+1. Move or keep the extension in its existing path
+2. Add to `lazy-extensions.json`:
+```json
+{
+  "version": 1,
+  "extensions": [
+    {
+      "name": "my-heavy-ext",
+      "path": "~/.pi/agent/extensions/my-heavy-ext.ts",
+      "lifecycle": "lazy",
+      "description": "My heavy extension with 5 tools",
+      "toolSummary": ["heavy_tool_1", "heavy_tool_2", "heavy_tool_3", "heavy_tool_4", "heavy_tool_5"]
+    }
+  ]
+}
+```
+3. Rename or remove the original from auto-discovery (add a `.bak` suffix or move it out of `~/.pi/agent/extensions/`) so it isn't loaded eagerly by pi itself
+
+---
+
+## Motivation
+
+This is an experiment. If the pattern proves useful, the goal is to propose a `pi.loadExtension(path)` method to the pi SDK that handles proper `sourceInfo` attribution, deduplication, and full lifecycle management. This package serves as a working prototype to validate the approach.
+
+### Module Resolution
+
+Lazy extensions are loaded via `jiti` — the same TypeScript/ESM transpiler that pi uses for its own extension loader. The jiti instance is configured with the same alias map that pi builds internally, which resolves:
+
+- `typebox` (and `typebox/compile`, `typebox/value`)
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-agent-core`
+- `@earendil-works/pi-tui`
+- `@earendil-works/pi-ai` (and `@earendil-works/pi-ai/oauth`)
+- `@sinclair/typebox` (legacy alias)
+
+This ensures lazy extensions can use the same imports as normally-loaded extensions. If jiti is unavailable (e.g. stripped from the runtime), the loader falls back to raw `import()`, which only works for `.js` files without SDK imports.
+
+## License
+
+MIT

package/config.ts

@@ -0,0 +1,152 @@
+/**
+ * Configuration loading for pi-lazy-extensions.
+ *
+ * Reads a manifest file (lazy-extensions.json) that describes which
+ * extensions to lazy-load and their metadata.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { LazyExtensionConfig, LazyExtensionsManifest, LazyExtensionsState, LoadedExtensionState } from "./types.js";
+
+/**
+ * Find and load the manifest file.
+ *
+ * Resolution order:
+ * 1. LAZY_EXTENSIONS_CONFIG env var (explicit path)
+ * 2. Project .pi/lazy-extensions.json
+ * 3. Global ~/.pi/agent/lazy-extensions.json
+ * 4. Project lazy-extensions.json
+ */
+export function loadManifest(cwd: string, agentDir: string): { manifest: LazyExtensionsManifest; path: string } | null {
+  const envPath = process.env.LAZY_EXTENSIONS_CONFIG;
+  if (envPath && existsSync(envPath)) {
+    const manifest = parseManifest(envPath);
+    if (manifest) return { manifest, path: resolve(envPath) };
+  }
+
+  // Project .pi dir
+  const projectPi = join(cwd, ".pi", "lazy-extensions.json");
+  if (existsSync(projectPi)) {
+    const manifest = parseManifest(projectPi);
+    if (manifest) return { manifest, path: projectPi };
+  }
+
+  // Global agent dir
+  const globalPath = join(agentDir, "lazy-extensions.json");
+  if (existsSync(globalPath)) {
+    const manifest = parseManifest(globalPath);
+    if (manifest) return { manifest, path: globalPath };
+  }
+
+  // Project root
+  const projectRoot = join(cwd, "lazy-extensions.json");
+  if (existsSync(projectRoot)) {
+    const manifest = parseManifest(projectRoot);
+    if (manifest) return { manifest, path: projectRoot };
+  }
+
+  return null;
+}
+
+function parseManifest(filePath: string): LazyExtensionsManifest | null {
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+
+    if (!parsed || typeof parsed !== "object") return null;
+    if (parsed.version !== 1) {
+      console.error(`pi-lazy-extensions: unsupported manifest version ${parsed.version}`);
+      return null;
+    }
+    if (!Array.isArray(parsed.extensions)) {
+      console.error("pi-lazy-extensions: manifest missing 'extensions' array");
+      return null;
+    }
+
+    // Validate entries
+    for (const ext of parsed.extensions as LazyExtensionConfig[]) {
+      if (!ext.name || typeof ext.name !== "string") {
+        console.error("pi-lazy-extensions: extension entry missing 'name'");
+        return null;
+      }
+      if (!ext.path || typeof ext.path !== "string") {
+        console.error(`pi-lazy-extensions: extension "${ext.name}" missing 'path'`);
+        return null;
+      }
+    }
+
+    return parsed as LazyExtensionsManifest;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`pi-lazy-extensions: failed to parse ${filePath}: ${message}`);
+    return null;
+  }
+}
+
+/**
+ * Expand leading ~ to the user's home directory.
+ * Mirrors the pi SDK's own expandPath() in its extension loader.
+ */
+function expandTilde(p: string): string {
+  if (p.startsWith("~/")) {
+    return join(homedir(), p.slice(2));
+  }
+  if (p === "~") {
+    return homedir();
+  }
+  return p;
+}
+
+/**
+ * Resolve an extension path relative to the manifest's base directory.
+ * Supports ~ expansion (e.g. "~/.pi/agent/extensions/todo.ts").
+ */
+export function resolveExtensionPath(extPath: string, baseDir: string): string {
+  const expanded = expandTilde(extPath);
+  if (isAbsolute(expanded)) return expanded;
+  return resolve(baseDir, expanded);
+}
+
+/**
+ * Build initial state from a loaded manifest.
+ */
+export function buildState(
+  manifest: LazyExtensionsManifest,
+  manifestPath: string,
+): LazyExtensionsState {
+  const baseDir = dirname(manifestPath);
+  const extensions = new Map<string, LoadedExtensionState>();
+
+  for (const config of manifest.extensions) {
+    extensions.set(config.name, {
+      config,
+      loaded: false,
+      factoryCalled: false,
+      registeredTools: [],
+      registeredCommands: [],
+      registeredShortcuts: [],
+      registeredFlags: [],
+      registeredRenderers: [],
+    });
+  }
+
+  return { extensions, manifest, manifestPath, baseDir, failureTracker: new Map() };
+}
+
+/**
+ * Determine which extensions should be loaded eagerly at startup.
+ */
+export function getEagerExtensions(state: LazyExtensionsState): LazyExtensionConfig[] {
+  const rawOverrides = state.manifest.settings?.eagerOverrides ?? "";
+  const eagerOverrides = new Set(
+    rawOverrides.split(",").map(s => s.trim()).filter(Boolean)
+  );
+
+  return state.manifest.extensions.filter(ext => {
+    if (eagerOverrides.has(ext.name)) return true;
+    const lifecycle = ext.lifecycle ?? "lazy";
+    return lifecycle === "eager" || lifecycle === "keep-alive";
+  });
+}

package/index.ts

@@ -0,0 +1,249 @@
+/**
+ * pi-lazy-extensions
+ *
+ * A pi extension that lazy-loads other extensions on demand,
+ * analogous to Anthropic's ToolSearch but for entire pi extensions.
+ *
+ * Usage:
+ *   1. Create a lazy-extensions.json manifest
+ *   2. Install this package: pi install npm:pi-lazy-extensions
+ *   3. The `ext` proxy tool lets the LLM discover and activate extensions
+ */
+
+import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { loadManifest, buildState, getEagerExtensions } from "./config.js";
+import { activateExtension, clearAllTimers, touchExtension } from "./registry.js";
+import { executeStatus, executeSearch, executeActivate, executeListTools } from "./proxy-modes.js";
+import type { LazyExtensionsState } from "./types.js";
+
+const PROXY_TOOL_DESCRIPTION =
+  "Extension gateway - discover, search, and activate extensions on demand. " +
+  "Call ext({}) for status, ext({ search: \"query\" }) to find extensions, " +
+  "ext({ activate: \"name\" }) to load one.";
+
+export default function lazyExtensions(pi: ExtensionAPI) {
+  let state: LazyExtensionsState | null = null;
+  let initPromise: Promise<void> | null = null;
+  let lifecycleGeneration = 0;
+
+  const getPiTools = (): ToolInfo[] => pi.getAllTools();
+  const agentDir = process.env.PI_AGENT_DIR ?? process.env.PI_CODING_AGENT_DIR ?? `${process.env.HOME}/.pi/agent`;
+
+  // Check for tool name collision before registering the proxy tool.
+  // Pi uses "first registration wins" — if another extension already
+  // registered a tool named "ext", our proxy would be silently skipped.
+  const existingTools = pi.getAllTools();
+  if (existingTools.some(t => t.name === "ext")) {
+    console.error(
+      "pi-lazy-extensions: another extension already registered a tool named 'ext'. " +
+      "The proxy tool will not be available. Use the /ext command instead, " +
+      "or remove the conflicting extension."
+    );
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    const generation = ++lifecycleGeneration;
+
+    // Clear previous state
+    if (state) {
+      clearAllTimers(state);
+      state = null;
+    }
+
+    const result = loadManifest(ctx.cwd, agentDir);
+
+    if (!result) {
+      // No manifest found — proxy tool still active, shows "not configured"
+      return;
+    }
+
+    // Honour disableProxyTool by removing the ext proxy from the active set
+    if (result.manifest.settings?.disableProxyTool) {
+      const active = pi.getActiveTools();
+      pi.setActiveTools(active.filter(t => t !== "ext"));
+      return;
+    }
+
+    state = buildState(result.manifest, result.path);
+    state.pi = pi;
+
+    if (generation !== lifecycleGeneration) return;
+
+    if (ctx.hasUI) {
+      const total = state.extensions.size;
+      if (total > 0) {
+        ctx.ui.notify(`Lazy Extensions: ${total} extension${total === 1 ? "" : "s"} configured`, "info");
+      }
+    }
+
+    // Load eager extensions immediately
+    const eager = getEagerExtensions(state);
+    if (eager.length > 0 && ctx.hasUI) {
+      ctx.ui.setStatus("lazy-ext", `Lazy Extensions: loading ${eager.length} eager extensions...`);
+    }
+
+    const init = (async () => {
+      for (const extConfig of eager) {
+        if (generation !== lifecycleGeneration) return;
+        const result = await activateExtension(extConfig.name, state!, pi);
+        if (!result.success && ctx.hasUI) {
+          ctx.ui.notify(`Lazy Extensions: failed to load "${extConfig.name}": ${result.error}`, "warning");
+        }
+      }
+    })();
+
+    initPromise = init;
+    await init;
+    initPromise = null;
+
+    if (generation !== lifecycleGeneration) return;
+
+    if (eager.length > 0 && ctx.hasUI) {
+      const loaded = eager.filter(e => state!.extensions.get(e.name)?.loaded).length;
+      ctx.ui.setStatus("lazy-ext", `Lazy Extensions: ${loaded}/${eager.length} eager loaded`);
+      // Clear status after a few seconds
+      setTimeout(() => {
+        if (state && generation === lifecycleGeneration) {
+          const active = Array.from(state.extensions.values()).filter(e => e.loaded).length;
+          const total = state.extensions.size;
+          if (active > 0) {
+            ctx.ui.setStatus("lazy-ext", ctx.ui.theme.fg("accent", `Ext: ${active}/${total} active`));
+          } else {
+            ctx.ui.setStatus("lazy-ext", undefined);
+          }
+        }
+      }, 3000);
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    ++lifecycleGeneration;
+    if (state) {
+      clearAllTimers(state);
+      state = null;
+    }
+    initPromise = null;
+  });
+
+  // Reset idle timers when lazy extension tools are used.
+  // Note: if a lazy extension's tool result arrives during session_start
+  // (after state is built but before initPromise resolves), touchExtension
+  // won't find the tool name and safely returns without touching. This is
+  // harmless — the idle timer hasn't started yet for that extension anyway.
+  pi.on("tool_execution_end", (event) => {
+    if (!state) return;
+    for (const [name, extState] of state.extensions) {
+      if (extState.loaded && extState.registeredTools.includes(event.toolName)) {
+        touchExtension(name, state);
+        break;
+      }
+    }
+  });
+
+  pi.registerCommand("ext", {
+    description: "Show lazy extensions status",
+    handler: async (args, ctx) => {
+      // Wait for init if still running
+      if (initPromise) await initPromise;
+
+      if (!state) {
+        if (ctx.hasUI) ctx.ui.notify("No lazy extensions configured", "info");
+        return;
+      }
+
+      const parts = args?.trim()?.split(/\s+/) ?? [];
+      const subcommand = parts[0] ?? "";
+      const target = parts[1];
+
+      switch (subcommand) {
+        case "activate": {
+          if (!target) {
+            if (ctx.hasUI) ctx.ui.notify("Usage: /ext activate <name>", "warning");
+            return;
+          }
+          const result = await activateExtension(target, state, pi);
+          if (result.success) {
+            const warnings: string[] = [];
+            if (result.duplicateTools?.length) warnings.push("duplicate tools");
+            if (result.sessionStartWarning) warnings.push("session_start won't fire");
+            const warnStr = warnings.length > 0 ? ` (⚠ ${warnings.join(", ")})` : "";
+            if (ctx.hasUI) ctx.ui.notify(`✓ Activated "${target}"${result.tools?.length ? ` (${result.tools.length} tools)` : ""}${warnStr}`, "info");
+          } else {
+            if (ctx.hasUI) ctx.ui.notify(`Failed to activate "${target}": ${result.error}`, "error");
+          }
+          break;
+        }
+        case "search": {
+          const query = parts.slice(1).join(" ");
+          if (!query) {
+            if (ctx.hasUI) ctx.ui.notify("Usage: /ext search <query>", "warning");
+            return;
+          }
+          const result = executeSearch(state, query);
+          const msg = result.content[0]?.type === "text" ? result.content[0].text : undefined;
+          if (ctx.hasUI) ctx.ui.notify(msg ?? "No results", "info");
+          break;
+        }
+        case "tools": {
+          const result = executeListTools(state, target, getPiTools);
+          const msg = result.content[0]?.type === "text" ? result.content[0].text : undefined;
+          if (ctx.hasUI) ctx.ui.notify(msg ?? "No tools", "info");
+          break;
+        }
+        case "status":
+        case "":
+        default: {
+          const result = executeStatus(state);
+          const msg = result.content[0]?.type === "text" ? result.content[0].text : undefined;
+          if (ctx.hasUI) ctx.ui.notify(msg ?? "No status", "info");
+          break;
+        }
+      }
+    },
+  });
+
+  // Register the proxy tool unconditionally — it's the LLM's entry point for
+  // discovering and activating extensions. If the manifest sets disableProxyTool,
+  // we remove "ext" from the active tool set in session_start.
+  // @ts-ignore - Type.Object causes excessive type instantiation with typebox
+  pi.registerTool({
+    name: "ext",
+    label: "Extension Gateway",
+    description: PROXY_TOOL_DESCRIPTION,
+    promptSnippet: "Discover and activate lazy-loaded extensions",
+    promptGuidelines: [
+      "Use ext to discover and activate extensions before using their tools.",
+      "If a tool you need is not available, search ext({ search: \"...\" }) for an extension that provides it.",
+      "After activating an extension with ext({ activate: \"name\" }), its tools become immediately available.",
+    ],
+    parameters: Type.Object({
+      search: Type.Optional(Type.String({ description: "Search extensions by name, description, tags, or tool names" })),
+      activate: Type.Optional(Type.String({ description: "Activate (load) an extension by name" })),
+      tools: Type.Optional(Type.String({ description: "List tools for a specific extension (or omit for all active)" })),
+      regex: Type.Optional(Type.Boolean({ description: "Treat search as regex (default: substring match)" })),
+    }),
+    async execute(_toolCallId: string, params: { search?: string; activate?: string; tools?: string; regex?: boolean }, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: ExtensionContext) {
+      // Wait for init if still running
+      if (initPromise) await initPromise;
+
+      if (!state) {
+        return {
+          content: [{ type: "text" as const, text: "No lazy extensions configured. Create a lazy-extensions.json manifest." }],
+          details: { error: "not_configured" },
+        };
+      }
+
+      if (params.activate) {
+        return executeActivate(state, params.activate, pi) as any;
+      }
+      if (params.search) {
+        return executeSearch(state, params.search, params.regex) as any;
+      }
+      if (params.tools !== undefined) {
+        return executeListTools(state, params.tools || undefined, getPiTools) as any;
+      }
+      return executeStatus(state) as any;
+    },
+  });
+}