Engine Interface & Base Classes
Relevant source files
The following files were used as context for generating this wiki page:
The Engine Interface & Base Classes form the core abstraction layer of the Morty project, enabling a unified way to interact with various AI-powered coding agents. This module provides the foundational structures and utilities required to translate high-level tasks into executable commands across different AI Command Line Interfaces (CLIs) such as Claude Code, OpenCode, Codex, and others.
By standardizing the communication patterns between Morty and external AI tools, this system allows the project to support a wide array of engines while maintaining consistent execution logic, progress tracking, and error handling. This architecture is critical for the project's ability to run tasks sequentially or in parallel across isolated worktrees.
Sources: cli/src/engines/base.ts, morty.sh:10-15
Architecture and Core Abstractions
The system is built around a provider-agnostic interface that defines how an AI engine should behave. This is primarily implemented through the AIEngine interface and the BaseAIEngine abstract class.
Engine Interface Definitions
The project uses TypeScript interfaces to define the contract for any AI engine. This ensures that every engine provides necessary metadata (like its name and CLI command) and implementation methods for executing prompts.
The diagram above shows the relationship between the core interface, the base class, and specific engine implementations.
Sources: cli/src/engines/types.ts:4-25, cli/src/engines/base.ts:251-266
Data Structures
Execution results and configuration options are passed using standardized data models.
| Interface | Property | Type | Description |
|---|---|---|---|
| AIResult | success | boolean | Indicates if the task completed successfully. |
response | string | The text result returned by the AI. | |
inputTokens | number | Number of input tokens used. | |
outputTokens | number | Number of output tokens used. | |
error | string | (Optional) Error message if execution failed. | |
| EngineOptions | modelOverride | string | (Optional) Specific model version to use for the engine. |
| Sources: cli/src/engines/types.ts:27-42 |
Base Engine Functionality
The BaseAIEngine class and associated utility functions in base.ts provide cross-platform command execution and output parsing.
Execution Utilities
The module includes robust handlers for spawning child processes, particularly addressing differences between Node.js and Bun runtimes, as well as OS-specific behavior for Windows.
commandExists: Checks if the engine's CLI is available in the system PATH usingwhichorwhere.execCommand: Executes a command and captures full stdout/stderr.execCommandStreaming: Executes commands while providing line-by-line feedback, enabling real-time progress monitoring.
Sources: cli/src/engines/base.ts:31-48, cli/src/engines/base.ts:153-170
Output Parsing Logic
A significant portion of the base logic is dedicated to parsing JSON streams, which is the standard output format for engines like Claude and Qwen.
This flow represents the logic contained within parseStreamJsonResult and checkForErrors.
Sources: cli/src/engines/base.ts:88-128
Step Detection
The detectStepFromOutput function uses heuristic analysis of the AI's tool usage (e.g., calling read, write, or git commit) to determine the current lifecycle stage of a task.
| Detected Step | Triggers |
|---|---|
| Reading code | Tool names: read, glob, grep |
| Implementing | Tool names: write, edit |
| Committing | Commands/Descriptions containing git commit |
| Testing | Commands: vitest, jest, bun test, pytest, etc. |
| Writing tests | Write operations to files matching *.test.* or *.spec.* |
Sources: cli/src/engines/base.ts:200-249
Engine Implementation Examples
Specific engines extend the base classes to handle their unique CLI signatures or output quirks.
Codex Engine
The CodexEngine handles tasks by utilizing a temporary file to capture the "last message" from the Codex CLI. It explicitly cleans up these files after execution.
Sources: cli/src/engines/codex.ts:13-35
Qwen Engine
The QwenEngine implements the executeStreaming method. It passes an onProgress callback to execCommandStreaming, which uses the base class's detectStepFromOutput to provide real-time updates to the UI.
Sources: cli/src/engines/qwen.ts:40-58
Integration with Execution Loop
The engine interface is utilized by both sequential and parallel execution handlers. In parallel mode, the engine is executed within isolated git worktrees.
Summary
The Engine Interface and Base Classes provide the necessary abstraction to decouple Morty's task management from the specifics of various AI providers. By leveraging a common AIEngine contract and a robust BaseAIEngine implementation, the system ensures that adding a new AI engine only requires implementing provider-specific command formatting and output parsing, while inheriting complex cross-platform execution and step-detection logic.