Morph API Integration Bridge

Relevant source files

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

• src/morph-clients.ts
• src/config.ts
• src/compaction.ts
• src/index.ts
• src/routing.ts
• AGENTS.md
• README.md

The Morph API Integration Bridge serves as the central orchestration layer between the oh-my-pi (omp) agent framework and the Morph LLM services. Its primary purpose is to extend the agent's capabilities with high-performance tools for code editing, codebase searching, and conversation compaction by wrapping the @morphllm/morphsdk.

Sources: README.md:1-10, package.json:15

Architectural Overview

The bridge is structured as a plugin that hooks into the ExtensionAPI of the oh-my-pi coding agent. It manages the lifecycle of SDK clients, handles configuration through environment variables, and registers specific event handlers and tools.

Client Lifecycle Management

The bridge initializes three distinct clients from the Morph SDK to handle different functional domains:

• MorphClient: Used for fast_edit (Fast Apply) operations.
• WarpGrepClient: Powers agentic natural-language search over local workspaces and GitHub.
• CompactClient: Manages session history compaction and targeted artifact digests.

Component Specifications

Configuration and Environment

The bridge is configured primarily via environment variables. If MORPH_API_KEY is missing, tools remain registered but return instructional guidance to the user instead of executing remote calls.

Variable	Default	Description
MORPH_API_KEY	Required	API key from morphllm.com.
MORPH_EDIT	true	Toggles the fast_edit tool.
MORPH_WARPGREP	true	Toggles local codebase_warpsearch.
MORPH_COMPACT	true	Toggles the session_before_compact hook.
MORPH_COMPACT_RATIO	0.3	Target fraction (0.05 to 1) of tokens to retain during compaction.

Sources: src/config.ts:1-35, README.md:27-37

Tool Integration Bridge

The bridge exports four main tools to the agent, each mapped to a specific Morph SDK capability:

1. fast_edit: Utilizes Morph Fast Apply to merge partial snippets containing // ... existing code ... markers into full files. It includes safety checks for "catastrophic truncation" and "marker leakage" to prevent code loss.
2. codebase_warpsearch: An agentic search tool that uses a multi-turn approach (ripgrep, file reading) to find relevant code context.
3. github_warpsearch: A grounded search tool for public GitHub repositories that does not require local cloning.
4. fastcompact: A tool for condensing specific files or artifacts into focused text.

Sources: src/tools/morph-edit.ts:14-45, src/tools/warpgrep.ts:25-50, README.md:39-66

Session Compaction Logic

The bridge hooks the session_before_compact event to replace native LLM summarization with Morph's specialized compaction API.

Compaction Data Flow

The bridge serializes agent messages into a format compatible with Morph, applying specific size constraints:

• Tool Call Arguments: Capped at 500 characters.
• Tool Results: Capped at 2,000 characters to prevent unbounded payload egress.
• Previous Summaries: Folded into the new request to maintain continuity.

Safety and Fallbacks

The bridge implements a "native floor" policy. It returns undefined to the host (triggering native fallback) in the following scenarios:

• MORPH_API_KEY is not configured.
• remoteEnabled is set to false (e.g., /compact soft).
• The strategy is snapcompact and no focus query is provided.
• The Morph API returns an empty summary or encounters an error.

Sources: src/compaction.ts:141-193, AGENTS.md:27-32

Routing and System Hints

The bridge dynamically modifies the agent's system prompt via the before_agent_start event. This provides the agent with "routing hints" that establish a preference for Morph-backed tools over native equivalents when specific conditions are met.

• Morph-First Preference: If a key is present, the agent is instructed to prefer fast_edit for scattered edits and warpsearch for exploratory queries.
• Native Floor: The agent is reminded that native edit is superior for trivial replacements and native write for new files.
• Unavailable State: If no key is configured, the hint explicitly tells the agent that Morph tools are unavailable.

Sources: src/routing.ts:41-86, src/index.ts:21-30

Conclusion

The Morph API Integration Bridge acts as a high-fidelity connector that prioritizes safety and performance. By implementing strict bounded buffers for data egress, complex symlink-aware path resolution for file writes, and a robust fallback mechanism to native tools, it ensures that Morph's advanced LLM capabilities enhance the agent's workflow without introducing instability.

Sources: src/format.ts:60-95, src/compaction.ts:70-90