Extension Initialization and State

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• src/config.ts
• src/routing.ts
• AGENTS.md
• src/compaction.ts
• package.json

The oh-my-pi-plugin-morph extension initializes by registering specialized tools and event hooks into the oh-my-pi (omp) environment. The primary purpose of this initialization is to extend the host agent's capabilities with Morph-backed LLM tools for code editing, search, and history compaction.

The extension follows a strict "closure state" architecture where mutable session state is encapsulated within the plugin factory function to prevent data leakage between concurrent agent sessions. This ensures that each invocation of the extension remains isolated and session-specific.
Sources: src/index.ts:16-18, AGENTS.md:28-30

Initialization Logic

The extension entry point is the morphPlugin function, which accepts the ExtensionAPI (aliased as pi). During execution, it conditionally registers tools and hooks based on environment variable flags.

The registration process uses standard omp extension patterns, such as pi.registerTool() and pi.on().
Sources: src/index.ts:16-41, AGENTS.md:28-30

Configuration State

The extension's operational state is driven by environment variables defined in src/config.ts. These variables control tool availability, API connectivity, and behavioral thresholds.

Variable	Default	Logic
MORPH_API_KEY	undefined	Required for remote tool execution. If missing, tools return guidance instead of errors.
MORPH_EDIT	true	Toggles the fast_edit tool registration.
MORPH_WARPGREP	true	Toggles the codebase_warpsearch tool registration.
MORPH_WARPGREP_GITHUB	true	Toggles the github_warpsearch tool registration.
MORPH_COMPACT	true	Toggles the session_before_compact event hook.
MORPH_ROUTING_HINT	true	Toggles the before_agent_start system prompt hint.
MORPH_COMPACT_RATIO	0.3	Target fraction of history to retain during compaction (0.05 to 1.0).

Sources: src/config.ts:1-35, README.md:46-55

Extension Lifecycle Hooks

The plugin utilizes two primary lifecycle hooks to manage agent behavior and session state.

Routing Guidance (before_agent_start)

This hook injects a system prompt hint into the agent at startup. The content of the hint dynamically changes based on the presence of the MORPH_API_KEY.

• Key Present: Instructions favor Morph-backed tools over native equivalents (e.g., fast_edit over edit).
• Key Absent: Instructions inform the agent that Morph tools are unavailable and to rely on native tools.

Sources: src/routing.ts:47-81, src/index.ts:22-34

Compaction Bridge (session_before_compact)

The extension hooks into omp's compaction event to substitute the native summarizer with Morph Compact.

The bridge yields to the host's native strategy if the MORPH_API_KEY is missing, an API error occurs, or the session uses the snapcompact strategy without specific focus text.
Sources: src/compaction.ts:133-189, AGENTS.md:14-26

Runtime State and Release Discipline

The extension enforces specific rules regarding versioning and state management to maintain stability across releases.

• Version Syncing: Any update must synchronize the version in package.json and the PLUGIN_VERSION constant in src/config.ts.
• Module Scope: Mutable state must not reside in the module scope to prevent leakage between sessions; it must be contained within the closure of the factory function.
• Tool Registration: Tools remain registered even if unconfigured (no API key) to ensure the agent is aware of their existence, but they will return setup guidance when called.

Sources: AGENTS.md:3-12, AGENTS.md:28-30, src/config.ts:21

Summary

Extension initialization is a conditional process governed by the environment. It sets up a suite of tools and hooks that prioritize Morph-backed functionality while maintaining fallback compatibility with native omp tools. The state management is designed for multi-session safety through functional closures.