Developer Build and Setup

Relevant source files

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

• README.md
• package.json
• AGENTS.md
• src/config.ts
• test/morph.test.ts

The oh-my-pi-plugin-morph project is an extension for the oh-my-pi (omp) ecosystem, designed to integrate Morph LLM capabilities such as fast_edit, warpsearch, and fastcompact into coding agents. This developer guide outlines the environment configuration, build processes, and testing protocols required to contribute to or deploy the plugin.

Sources: README.md:1-8, package.json:2-3

Project Prerequisites and Installation

The project is built using the Bun runtime and TypeScript. Development requires a Morph API key for full functionality, though tools remain registered in a degraded state without one.

Installation Steps

1. Clone and Install Dependencies: Use Bun to install the necessary packages.

   bun install
   

2. Link the Plugin: For local development, link the current directory to the omp environment.

   omp plugin link .
   

3. Environment Setup: Set the mandatory Morph API key.

   export MORPH_API_KEY="sk-..."
   

Sources: README.md:11-20, README.md:104-106, package.json:11-15

Build and Verification Lifecycle

The project follows a strict release discipline and verification gate policy to ensure consistency between metadata and runtime constants.

Verification Gates

Developers must run the following commands before committing or pushing changes:

• Type Checking: bun run typecheck (executes tsc --noEmit).
• Unit Testing: bun test ./test.
• Documentation Scans: For root docs, use omp ttsr scan with the md-ai-formatting-tells filter.

Sources: AGENTS.md:33-41, package.json:8-9

Release Discipline

Any shipped update must adhere to the following synchronization rule:

1. Bump version in package.json.
2. Update PLUGIN_VERSION in src/config.ts.
3. Move [Unreleased] content in CHANGELOG.md to a dated heading for the new version.

Sources: AGENTS.md:3-6, src/config.ts:16

Build Process Flow

This diagram illustrates the developer workflow from code change to verification.

The flow ensures that type safety, functional tests, and documentation formatting are verified before the release synchronization steps occur.
Sources: AGENTS.md:3-41, package.json:8-9

Configuration and Environment Variables

Configuration is handled entirely through environment variables. These variables control feature flags for specific tools and API behaviors.

Variable	Default	Description
MORPH_API_KEY	(None)	Required for API calls. If missing, tools provide setup guidance instead of executing.
MORPH_EDIT	true	Toggles the fast_edit tool.
MORPH_WARPGREP	true	Toggles local codebase_warpsearch.
MORPH_WARPGREP_GITHUB	true	Toggles github_warpsearch.
MORPH_COMPACT	true	Toggles the session_before_compact history hook.
MORPH_FASTCOMPACT	true	Toggles the standalone fastcompact tool.
MORPH_ROUTING_HINT	true	Enables system hints for tool selection in agents.
MORPH_COMPACT_RATIO	0.3	Target fraction (0.05 to 1.0) for history compaction.

Sources: README.md:32-41, src/config.ts:1-32

Architecture and Integration

The plugin integrates with the host oh-my-pi via an extension factory. It registers tools and hooks based on the configured environment variables.

Tool Registration Sequence

The factory pattern ensures that session-specific state remains isolated within the closure of the morphPlugin(pi) call, preventing data leakage between concurrent agent sessions.
Sources: AGENTS.md:28-31, src/index.ts:17-38

Testing Infrastructure

Tests are located in the test/ directory and use the bun:test runner. The test suite covers:

• Format Helpers: Validating markdown normalization and XML escaping.
• Security Gates: Testing path resolution and symlink containment to prevent workspace escapes.
• Compaction Bridge: Ensuring message serialization for the Morph API is accurate and respects size budgets.
• Tool Execution: Mocking the Morph SDK to verify fast_edit and warpsearch logic under various API responses.

Sources: test/morph.test.ts:1-25, test/morph.test.ts:145-180

Workspace Containment Logic

The project implements strict path resolution to prevent the agent from accessing files outside the workspace via symlinks or relative paths.

Summary

The developer environment for oh-my-pi-plugin-morph is centered around the Bun runtime and a robust set of environment-driven configuration options. By adhering to the mandatory verification gates and release synchronization rules, developers can ensure the plugin provides a secure and reliable bridge between coding agents and the Morph LLM API.