What Is the Role of context-compat.ts in the i-have-adhd Project?

The context-compat.ts module serves as a runtime compatibility layer that normalizes session-manager APIs between Pi and OMP environments, allowing the i-have-adhd extension to safely inspect conversation context and determine whether ADHD rules are active without crashing on platform-specific differences.

The extensions/context-compat.ts file within the ayghri/i-have-adhd repository solves a critical interoperability challenge for VS Code extensions supporting multiple AI runtimes. Because Pi and OMP expose different session-manager methods for retrieving conversation context, the extension risks platform-specific failures without an abstraction layer. This module provides a unified API for context inspection while implementing fail-open safeguards to ensure stability across runtime environments.

The Runtime API Compatibility Challenge

The i-have-adhd extension must inspect conversation history to determine whether its ADHD ruleset is already present or has been disabled. However, the two supported runtimes expose this functionality through incompatible APIs:

• Pi runtime: Implements buildContextEntries(), which returns an array of custom message objects directly.
• OMP runtime: Implements buildSessionContext(), which returns an object containing a messages property that holds the array.

Directly invoking these runtime-specific methods would couple the extension to a single platform and create brittle code vulnerable to API changes. The context-compat.ts module eliminates this coupling by providing a single entry point for context retrieval.

How context-compat.ts Normalizes Session-Manager APIs

The module exports two primary functions that abstract away runtime differences and provide defensive programming guarantees.

Universal Context Retrieval with contextMessages()

The contextMessages(sessionManager) function accepts a session manager object and returns a standardized array of ContextMessageMarker objects regardless of which underlying method the manager implements.

import { contextMessages } from "./context-compat";

// Works with both OMP-style managers...
const ompMgr = {
  buildSessionContext: () => ({ messages: [{ role: "custom", customType: "i-have-adhd-rules" }] })
};

// ...and Pi-style managers
const piMgr = {
  buildContextEntries: () => [{ type: "custom_message", customType: "i-have-adhd-rules" }]
};

// Both return the same normalized structure
console.assert(contextMessages(ompMgr).length === 1);
console.assert(contextMessages(piMgr).length === 1);

Fail-Open Error Handling

If the session manager is null, not an object, or throws an exception while building context, contextMessages() returns an empty array rather than crashing. This fail-open behavior prevents the extension from breaking during session startup when the manager might be uninitialized or in an unexpected state.

Context Marker Evaluation with latestMarkerIsActive()

The latestMarkerIsActive(messages, activeType, disabledType) function evaluates the normalized message array to determine the current state of the ADHD ruleset. It traverses the messages and returns true only if the most recent custom marker of activeType has not been overridden by a subsequent disabledType marker.

import { latestMarkerIsActive } from "./context-compat";

const ACTIVE = "i-have-adhd-rules";
const DISABLED = "i-have-adhd-disabled";

const markers = [
  { role: "custom", customType: ACTIVE },
  { role: "custom", customType: DISABLED },
  { role: "custom", customType: ACTIVE },
];

// Returns true because the final marker is ACTIVE
console.assert(latestMarkerIsActive(markers, ACTIVE, DISABLED) === true);

Integration with the Main Extension Logic

The i-have-adhd.ts file consumes these compatibility helpers within its rulesAreInContext() function to decide whether to inject or re-inject the ADHD rules. This integration demonstrates the practical application of the abstraction layer:

import { contextMessages, latestMarkerIsActive } from "./context-compat";

function rulesAreInContext(ctx: ExtensionContext): boolean {
  return latestMarkerIsActive(
    contextMessages(ctx.sessionManager),   // ← works for Pi & OMP
    "i-have-adhd-rules",                  // active marker type
    "i-have-adhd-disabled",               // disabled marker type
  );
}

By delegating platform detection and normalization to context-compat.ts, the main extension logic remains clean, testable, and resilient to changes in the underlying runtime implementations. The module is validated by unit-style checks in scripts/check_context_compat.ts, which verify both runtime simulations behave identically through the compatibility layer.

Summary

• context-compat.ts bridges incompatible session-manager APIs between Pi (buildContextEntries()) and OMP (buildSessionContext()) runtimes.
• The contextMessages() function provides a unified interface that returns a normalized array of context markers regardless of the underlying platform.
• Fail-open error handling ensures the extension returns an empty array rather than crashing when session managers are null or throw exceptions.
• latestMarkerIsActive() implements state-tracking logic to determine whether ADHD rules are currently active based on custom marker history.
• This abstraction enables i-have-adhd.ts to inspect conversation context safely without platform-specific conditional logic.

Frequently Asked Questions

What is the difference between Pi and OMP session-manager APIs?

Pi exposes conversation context through buildContextEntries(), which returns an array of custom message objects directly, while OMP uses buildSessionContext(), which returns an object containing a messages property that holds the array. The context-compat.ts module in the i-have-adhd project normalizes these differences so the extension works identically on both platforms.

How does context-compat.ts handle errors or null session managers?

The module implements fail-open error handling where contextMessages() returns an empty array if the session manager is null, not an object, or throws an exception while building the context. This prevents the extension from crashing during session startup when the manager might be unavailable or in an unexpected state.

What are context markers and how does the extension use them?

Context markers are custom metadata objects injected into the conversation history with types like "i-have-adhd-rules" and "i-have-adhd-disabled". The latestMarkerIsActive() function evaluates these markers to determine whether the ADHD ruleset is currently active, allowing the extension to avoid duplicate injections or re-enable rules when appropriate.

Where can I find the test suite for the compatibility layer?

The project includes validation tests in scripts/check_context_compat.ts, which contains standalone assertions that verify both Pi and OMP style managers produce identical normalized outputs when processed through the context-compat.ts utilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}