App Server Protocol Types in the OpenAI Codex Plugin: Complete Reference

The app server protocol types in openai/codex-plugin-cc are defined in plugins/codex/scripts/lib/app-server-protocol.d.ts and consist of client configuration interfaces, RPC method mappings, and generic type helpers that enforce compile-time type safety for all App Server communications.

The openai/codex-plugin-cc repository implements a strictly typed communication layer between the Codex plugin and the App Server. Central to this implementation is the app server protocol defined in plugins/codex/scripts/lib/app-server-protocol.d.ts, which exports TypeScript interfaces and utility types that govern how the client initializes connections, invokes remote procedures, and handles asynchronous notifications.

Core Protocol Type Definitions

The protocol file exports seven primary type definitions that work together to create a type-safe RPC boundary.

CodexAppServerClientOptions

CodexAppServerClientOptions (lines 50-57 in app-server-protocol.d.ts) defines the configuration object required when instantiating an App Server client. This interface includes optional fields for environment variables, client metadata, capability advertisements, and broker connection settings such as brokerEndpoint and reuseExistingBroker.

AppServerMethodMap

AppServerMethodMap (lines 60-69) serves as the canonical dictionary of every RPC method exposed by the server. Each key in this map represents a method name, with corresponding params and result properties that reference the generated types from .generated/app-server-types/*. This explicit enumeration creates a single source of truth for the server's API contract.

Type-Safe RPC Helpers

Three generic types extract specific method signatures from AppServerMethodMap:

• AppServerMethod (line 71) – A string literal union of all available method names (keyof AppServerMethodMap).
• AppServerRequestParams<M> (line 72) – Extracts the parameter type for a specific method M from the map.
• AppServerResponse<M> (line 73) – Extracts the return type for method M, ensuring that client.call() returns a properly typed Promise.

Notification Types

For server-initiated asynchronous messages:

• AppServerNotification (line 74) – Re-exports ServerNotification from the generated types, defining the shape of unsolicited server messages like progress updates.
• AppServerNotificationHandler (line 75) – Defines the callback signature (notification: AppServerNotification) => void used to register handlers for incoming notifications.

Architecture Integration

The protocol types bridge generated schema definitions and the runtime client implementation.

Generated Type Definitions

The protocol imports low-level request and response shapes from ../../.generated/app-server-types/*. These TypeScript definitions are auto-generated from the server's OpenAPI or JSON-RPC schema and include concrete types like InitializeParams and ThreadStartResponse.

Runtime Client Consumption

In app-server.mjs, the runtime client consumes these protocol definitions. When createAppServerClient() receives a CodexAppServerClientOptions object, it uses the type information to configure the broker endpoint and advertise capabilities to the server.

Typed Method Invocation

Using the generic helpers, the client exposes methods where TypeScript validates both the request parameters and expected return type. For example, calling client.call('thread/start', params) requires params to match ThreadStartParams and returns a Promise<ThreadStartResponse>, catching type mismatches at compile time rather than runtime.

Asynchronous Notification Handling

The server pushes notifications via the AppServerNotification type. Client code registers an AppServerNotificationHandler callback to process these messages type-safely, enabling reactive updates for long-running operations like code reviews or thread synchronization.

Implementation Examples

Creating a Client with Custom Configuration

import { CodexAppServerClientOptions } from './app-server-protocol';
import { createAppServerClient } from './app-server';

const options: CodexAppServerClientOptions = {
  env: process.env,
  clientInfo: { name: 'my-plugin', version: '1.0.0' },
  capabilities: { supportsThreadResume: true },
  brokerEndpoint: 'http://localhost:8080',
  reuseExistingBroker: true,
};

const client = createAppServerClient(options);

Making Type-Safe RPC Calls

// ThreadStartParams and ThreadStartResponse come from generated types
const threadParams = { name: 'demo-thread', persistExtendedHistory: false };
const threadResult = await client.call('thread/start', threadParams);
// threadResult is automatically typed as ThreadStartResponse
console.log('Thread created:', threadResult.threadId);

Handling Server Notifications

client.onNotification((msg: AppServerNotification) => {
  if (msg.method === 'review/progress') {
    console.log('Review progress:', msg.params);
  }
});

Key Protocol Files

• plugins/codex/scripts/lib/app-server-protocol.d.ts – Central type definitions for the app server protocol, including CodexAppServerClientOptions and AppServerMethodMap.
• plugins/codex/scripts/lib/app-server.mjs – Runtime client implementation that instantiates connections using the protocol types.
• .generated/app-server-types/*.ts – Auto-generated TypeScript definitions derived from the server schema, imported by the protocol file.
• plugins/codex/scripts/codex-companion.mjs – Reference implementation demonstrating client consumption of the protocol API.

Summary

• The app server protocol types are defined in app-server-protocol.d.ts and provide the TypeScript foundation for all App Server communications in the Codex plugin.
• CodexAppServerClientOptions configures client initialization with environment details, capabilities, and broker settings.
• AppServerMethodMap enumerates every available RPC method with strictly typed parameters and results.
• Generic helpers AppServerRequestParams<M> and AppServerResponse<M> extract specific types from the method map, enabling compile-time validation of RPC calls.
• AppServerNotification and AppServerNotificationHandler type the asynchronous message flow from server to client.
• The protocol imports generated types from .generated/app-server-types/* and is consumed by the runtime client in app-server.mjs.

Frequently Asked Questions

What is the purpose of the AppServerMethodMap type?

AppServerMethodMap acts as a central registry that maps every RPC method name to its exact parameter and result types. According to the openai/codex-plugin-cc source code, this dictionary (defined at lines 60-69 in app-server-protocol.d.ts) ensures that when you call a method like thread/start, TypeScript knows to expect ThreadStartParams and returns ThreadStartResponse, preventing runtime type mismatches.

How does the plugin handle type-safe RPC method calls?

The plugin uses generic type helpers to enforce type safety. When invoking client.call('methodName', params), the AppServerRequestParams generic extracts the correct parameter type for that specific method from AppServerMethodMap, while AppServerResponse extracts the return type. This happens at lines 72-73 in app-server-protocol.d.ts, allowing IDEs to provide autocomplete and compile-time type checking.

Where are the concrete request and response types defined?

Concrete type definitions (like InitializeParams or ThreadStartResponse) are auto-generated from the server's OpenAPI or JSON-RPC schema and stored in ../../.generated/app-server-types/*. The app-server-protocol.d.ts file imports and references these generated types within its method map, separating the protocol structure from the evolving server schema.

What configuration options does CodexAppServerClientOptions support?

CodexAppServerClientOptions (lines 50-57) accepts the environment object, client metadata via clientInfo, capability flags, and broker connection settings. Key optional fields include brokerEndpoint for specifying the server URL and reuseExistingBroker to control connection pooling, enabling the same client code to operate across development, CI, and production environments.

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