Compare commits

...

3 Commits

Author SHA1 Message Date
Eric Traut
116ddfbb7a Remove app-server v1 doc references 2026-05-26 09:07:12 -07:00
Eric Traut
a591b76b46 Address remaining protocol path references 2026-05-26 09:05:47 -07:00
Eric Traut
6cc8cdb2b7 Fix stale app-server protocol paths 2026-05-26 08:53:02 -07:00
3 changed files with 10 additions and 10 deletions

View File

@@ -178,17 +178,17 @@ If you dont have the tool:
These guidelines apply to app-server protocol work in `codex-rs`, especially:
- `app-server-protocol/src/protocol/common.rs`
- `app-server-protocol/src/protocol/v2.rs`
- `app-server-protocol/src/protocol/v2/`
- `app-server/README.md`
### Core Rules
- All active API development should happen in app-server v2. Do not add new API surface area to v1.
- All active API development should happen in app-server v2.
- Follow payload naming consistently:
`*Params` for request payloads, `*Response` for responses, and `*Notification` for notifications.
- Expose RPC methods as `<resource>/<method>` and keep `<resource>` singular (for example, `thread/read`, `app/list`).
- Always expose fields as camelCase on the wire with `#[serde(rename_all = "camelCase")]` unless a tagged union or explicit compatibility requirement needs a targeted rename.
- Exception: config RPC payloads are expected to use snake_case to mirror config.toml keys (see the config read/write/list APIs in `app-server-protocol/src/protocol/v2.rs`).
- Exception: config RPC payloads are expected to use snake_case to mirror config.toml keys (see the config read/write/list APIs in `app-server-protocol/src/protocol/v2/`).
- Always set `#[ts(export_to = "v2/")]` on v2 request/response/notification types so generated TypeScript lands in the correct namespace.
- Never use `#[serde(skip_serializing_if = "Option::is_none")]` for v2 API payload fields.
Exception: client->server requests that intentionally have no params may use:

View File

@@ -1906,7 +1906,7 @@ Use this checklist when introducing a field/method that should only be available
At runtime, clients must send `initialize` with `capabilities.experimentalApi = true` to use experimental methods or fields.
1. Annotate the field in the protocol type (usually `app-server-protocol/src/protocol/v2.rs`) with:
1. Annotate the field in the relevant protocol type under `app-server-protocol/src/protocol/v2/` with:
```rust
#[experimental("thread/start.myField")]
pub my_field: Option<String>,

View File

@@ -8,7 +8,7 @@ This document describes Codex's experimental MCP server interface: a JSON-RPC AP
## Overview
Codex exposes MCP-compatible methods to manage threads, turns, accounts, config, and approvals. The types live in `app-server-protocol/src/protocol/{common,v1,v2}.rs` and are consumed by the app server implementation in `app-server/`.
Codex exposes MCP-compatible methods to manage threads, turns, accounts, config, and approvals. Shared protocol definitions live in `app-server-protocol/src/protocol/common.rs`; v2 types live under `app-server-protocol/src/protocol/v2/`. The app server implementation in `app-server/` consumes those protocol definitions.
At a glance:
@@ -18,7 +18,7 @@ At a glance:
- `account/read`, `account/login/start`, `account/login/cancel`, `account/logout`, `account/rateLimits/read`
- `config/read`, `config/value/write`, `config/batchWrite`
- `model/list`, `app/list`, `collaborationMode/list`
- Remaining v1 compatibility RPCs
- Deprecated compatibility RPCs
- `getConversationSummary`
- `getAuthStatus`
- `gitDiffToRemote`
@@ -30,7 +30,7 @@ At a glance:
- Approvals (server -> client requests)
- `applyPatchApproval`, `execCommandApproval`
See code for full type definitions and exact shapes: `app-server-protocol/src/protocol/{common,v1,v2}.rs`.
See code for full type definitions and exact shapes: `app-server-protocol/src/protocol/common.rs` and `app-server-protocol/src/protocol/v2/`.
## Starting the server
@@ -54,7 +54,7 @@ Use the v2 thread and turn APIs for all new integrations. `thread/start` creates
`getConversationSummary` remains as a compatibility helper for clients that still need a summary lookup by `conversationId` or `rolloutPath`. Lookups by `conversationId` are preferred; lookups by `rolloutPath` won't work with non-local thread stores.
For complete request and response shapes, see the app-server README and the protocol definitions in `app-server-protocol/src/protocol/v2.rs`.
For complete request and response shapes, see the app-server README and the protocol definitions in `app-server-protocol/src/protocol/v2/`.
## Models
@@ -132,7 +132,7 @@ For the complete request/response shapes and flow examples, see the [Auth endpoi
## Legacy compatibility methods
The server still accepts a narrow v1 compatibility surface for existing app clients:
The server still accepts a narrow deprecated compatibility surface for existing app clients:
- `getConversationSummary`
- `getAuthStatus`
@@ -141,4 +141,4 @@ The server still accepts a narrow v1 compatibility surface for existing app clie
## Compatibility and stability
This interface is experimental. Method names, fields, and event shapes may evolve. For the authoritative schema, consult `app-server-protocol/src/protocol/{common,v1,v2}.rs` and the corresponding server wiring in `app-server/`.
This interface is experimental. Method names, fields, and event shapes may evolve. For the authoritative schema, consult `app-server-protocol/src/protocol/common.rs`, `app-server-protocol/src/protocol/v2/`, and the corresponding server wiring in `app-server/`.