🔌 OMP Extension Protocols

This document summarizes the development and patching protocols for Oh My Pi (OMP) extensions and the local Quartz 5 plugin ecosystem.

1. OMP Extension Development

When writing or modifying OMP extensions, strictly adhere to the following invariants to ensure stability and data safety:

The 4 Golden Invariants

1. Zero-Blocking: Never await network or heavy I/O operations in event handlers. Push payloads to an internal queue and use an out-of-band setInterval flusher.
2. Zero-Crashing: Wrap all pi.on bindings in a try/catch block. Unhandled promise rejections or exceptions in extension hooks will crash the main OMP agent process.
3. Zero-Leakage: tool_call and before_provider_request payloads contain raw LLM prompts, which often include user API keys and JWTs. Strict regex redaction is required before storing or transmitting payload data.
4. Zero-State-Corruption (Concurrency Safe): OMP agents run concurrently. Never use global scalar variables to track state. Instead, use ID-keyed Maps.
   • Generation State: Map to ev.id, ev.messageId, or ev.generationId. NEVER map to ev.agentId, as a single agent turn involves multiple generations.
   • Turn State: Map to ev.id or ev.turnId.
   • Agent State: Map to ev.agentId.

2. Quartz OMP Plugin Patching

The quartz-omp ecosystem utilizes a YAML-driven architecture rather than the standard quartz.config.ts.

Configuration and Vendoring

• All configuration modifications must target quartz.config.yaml or quartz.config.default.yaml.
• External plugins (e.g., github:quartz-community/article-title) that require patching must be vendored locally:
  1. Copy the cached plugin from .quartz/plugins/<plugin-name> to quartz/local-plugins/<plugin-name>.
  2. Update quartz.config.yaml to point to the local path: source: ./quartz/local-plugins/<plugin-name>.

Build Process and Cross-Plugin Imports

• Every plugin inside quartz/local-plugins/ functions as an isolated NPM package. After modifying a local plugin’s source files, you must run:

  cd quartz/local-plugins/<plugin-name>
  npm install
  npm run build

• If a plugin requires imports from outside its immediate directory hierarchy, TypeScript will fail to generate .d.ts definitions. To resolve this, remove the "rootDir": "." property from the plugin’s tsconfig.json before building.

Workerpool and AST Parsing

• When utilizing workerpool for parallel processing of ASTs or markdown files in Quartz, note that objects passed across the IPC boundary lose their prototypes. For instance, VFile instances returned from workers MUST be manually reconstructed (e.g., new VFile(fileObj)) before they are handed off to unified plugins to prevent prototype loss crashes (Zero-Crashing).