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

> Explore the app server protocol types in the OpenAI Codex plugin. Understand client configuration, RPC mappings, and type helpers for secure App Server communications.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: api-reference
- Published: 2026-08-02

---

**The app server protocol types in `openai/codex-plugin-cc` are defined in [`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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

```typescript
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

```typescript
// 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

```typescript
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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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.