Type-Safe Configuration Parsing

Relevant source files

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

• src/config.ts
• src/index.ts
• src/routing.ts
• src/tools/morph-edit.ts
• src/tools/warpgrep.ts
• test/morph.test.ts

Type-safe configuration parsing in the oh-my-pi-plugin-morph project ensures that environment variables are correctly validated and transformed into usable constants before being consumed by the extension's tools and event handlers. This system acts as a central guardrail, defining which features (like fast_edit or codebase_warpsearch) are enabled and ensuring that numerical constraints, such as compaction ratios, remain within valid bounds.

The architecture relies on a combination of standard environment variable access, explicit type checks, and schema-based validation for tool parameters. By centralizing these definitions in src/config.ts, the project maintains a single source of truth for runtime behavior and feature flagging.

Centralized Configuration Architecture

The project utilizes src/config.ts to process raw environment variables into typed constants. This process includes default value assignment, string-to-boolean conversion, and range validation for numeric inputs.

Environment Variable Processing

Variables are parsed from process.env. Boolean flags follow a "default-on" pattern where only an explicit "false" string disables the feature. Numeric values, such as the MORPH_COMPACT_RATIO, are parsed via parseFloat and validated against specific constraints to prevent runtime errors.

The diagram shows the transformation of raw environment variables into sanitized, exported constants.
Sources: src/config.ts:1-41, test/morph.test.ts:1008-1025

Configuration Schema

Variable	Type	Default	Description
MORPH_API_KEY	string	undefined	Required for Morph API communication.
MORPH_EDIT	boolean	true	Enables or disables the fast_edit tool.
MORPH_WARPGREP	boolean	true	Enables or disables codebase search.
MORPH_COMPACT_RATIO	number	0.3	Target ratio for history compaction (0.05 to 1.0).
FASTCOMPACT_MAX_BYTES	number	1,048,576	Hard limit for file input size in bytes.

Sources: src/config.ts:19-41, README.md:33-42

Tool Parameter Validation

While global configuration is handled in src/config.ts, individual tools utilize zod for type-safe parsing of input parameters at the execution boundary. This ensures that arguments passed by the agent (such as file paths or search terms) conform to the expected types and constraints.

Schema Definition and Execution

Tools like fast_edit and codebase_warpsearch define a parameters object using pi.zod. These schemas are used by the host to validate the agent's tool calls before the execute function is invoked.

The sequence shows how zod schemas are used to guard tool execution with type-safe parameters.
Sources: src/tools/morph-edit.ts:41-51, src/tools/warpgrep.ts:37-41

Feature Flagging and Conditional Registration

The configuration constants directly control the lifecycle of the plugin. During the initialization phase in src/index.ts, feature flags determine which tools and hooks are registered with the ExtensionAPI.

Registration Logic

The morphPlugin function checks the state of enabled constants (e.g., MORPH_EDIT_ENABLED) before calling pi.registerTool or pi.on. This allows the extension to minimize its footprint and avoid advertising unavailable tools to the agent.

// src/index.ts:13-16
export default function morphPlugin(pi: ExtensionAPI): void {
  if (MORPH_EDIT_ENABLED) pi.registerTool(makeMorphEdit(pi));
  if (MORPH_WARPGREP_ENABLED) pi.registerTool(makeWarpgrepCodebase(pi));
  // ...
}

Sources: src/index.ts:12-32, test/morph.test.ts:983-1006

Runtime Guidance and Routing

The system-safe parsing of configuration also affects the "Routing Hints" provided to the agent. If the MORPH_API_KEY is missing or specific features are disabled, the buildMorphSystemRoutingHint function generates different instructions to steer the agent toward native tools when Morph is unavailable.

• Unconfigured State: If MORPH_API_KEY is absent, the system prompt explicitly warns that Morph tools are unavailable.
• Configured State: If present, it advises the agent to favor Morph-backed tools like fast_edit for complex tasks while retaining a "native floor" for trivial operations.

Sources: src/routing.ts:40-75, AGENTS.md:12-16

Summary of Constraints and Limits

To ensure stability, the configuration enforces several hard-coded numeric limits that are checked during parsing or tool execution.

Constraint	Value	File Reference
API Timeout	30,000ms	src/config.ts
WarpGrep Timeout	60,000ms	src/config.ts
Max FastCompact Bytes	1,048,576	src/config.ts
Max FastCompact Locations	10	src/config.ts
Max Query Bytes	16,384	src/config.ts

Sources: src/config.ts:7-46