Files
codex/codex-rs/app-server-protocol/schema/json/v2/ItemStartedNotification.json
Michael Bolin 66447d5d2c feat: replace custom mcp-types crate with equivalents from rmcp (#10349)
We started working with MCP in Codex before
https://crates.io/crates/rmcp was mature, so we had our own crate for
MCP types that was generated from the MCP schema:


8b95d3e082/codex-rs/mcp-types/README.md

Now that `rmcp` is more mature, it makes more sense to use their MCP
types in Rust, as they handle details (like the `_meta` field) that our
custom version ignored. Though one advantage that our custom types had
is that our generated types implemented `JsonSchema` and `ts_rs::TS`,
whereas the types in `rmcp` do not. As such, part of the work of this PR
is leveraging the adapters between `rmcp` types and the serializable
types that are API for us (app server and MCP) introduced in #10356.

Note this PR results in a number of changes to
`codex-rs/app-server-protocol/schema`, which merit special attention
during review. We must ensure that these changes are still
backwards-compatible, which is possible because we have:

```diff
- export type CallToolResult = { content: Array<ContentBlock>, isError?: boolean, structuredContent?: JsonValue, };
+ export type CallToolResult = { content: Array<JsonValue>, structuredContent?: JsonValue, isError?: boolean, _meta?: JsonValue, };
```

so `ContentBlock` has been replaced with the more general `JsonValue`.
Note that `ContentBlock` was defined as:

```typescript
export type ContentBlock = TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource;
```

so the deletion of those individual variants should not be a cause of
great concern.

Similarly, we have the following change in
`codex-rs/app-server-protocol/schema/typescript/Tool.ts`:

```
- export type Tool = { annotations?: ToolAnnotations, description?: string, inputSchema: ToolInputSchema, name: string, outputSchema?: ToolOutputSchema, title?: string, };
+ export type Tool = { name: string, title?: string, description?: string, inputSchema: JsonValue, outputSchema?: JsonValue, annotations?: JsonValue, icons?: Array<JsonValue>, _meta?: JsonValue, };
```

so:

- `annotations?: ToolAnnotations` ➡️ `JsonValue`
- `inputSchema: ToolInputSchema` ➡️ `JsonValue`
- `outputSchema?: ToolOutputSchema` ➡️ `JsonValue`

and two new fields: `icons?: Array<JsonValue>, _meta?: JsonValue`

---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/10349).
* #10357
* __->__ #10349
* #10356
2026-02-02 17:41:55 -08:00

1040 lines
24 KiB
JSON

{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ByteRange": {
"properties": {
"end": {
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"start": {
"format": "uint",
"minimum": 0.0,
"type": "integer"
}
},
"required": [
"end",
"start"
],
"type": "object"
},
"CollabAgentState": {
"properties": {
"message": {
"type": [
"string",
"null"
]
},
"status": {
"$ref": "#/definitions/CollabAgentStatus"
}
},
"required": [
"status"
],
"type": "object"
},
"CollabAgentStatus": {
"enum": [
"pendingInit",
"running",
"completed",
"errored",
"shutdown",
"notFound"
],
"type": "string"
},
"CollabAgentTool": {
"enum": [
"spawnAgent",
"sendInput",
"wait",
"closeAgent"
],
"type": "string"
},
"CollabAgentToolCallStatus": {
"enum": [
"inProgress",
"completed",
"failed"
],
"type": "string"
},
"CommandAction": {
"oneOf": [
{
"properties": {
"command": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"type": {
"enum": [
"read"
],
"title": "ReadCommandActionType",
"type": "string"
}
},
"required": [
"command",
"name",
"path",
"type"
],
"title": "ReadCommandAction",
"type": "object"
},
{
"properties": {
"command": {
"type": "string"
},
"path": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"listFiles"
],
"title": "ListFilesCommandActionType",
"type": "string"
}
},
"required": [
"command",
"type"
],
"title": "ListFilesCommandAction",
"type": "object"
},
{
"properties": {
"command": {
"type": "string"
},
"path": {
"type": [
"string",
"null"
]
},
"query": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"search"
],
"title": "SearchCommandActionType",
"type": "string"
}
},
"required": [
"command",
"type"
],
"title": "SearchCommandAction",
"type": "object"
},
{
"properties": {
"command": {
"type": "string"
},
"type": {
"enum": [
"unknown"
],
"title": "UnknownCommandActionType",
"type": "string"
}
},
"required": [
"command",
"type"
],
"title": "UnknownCommandAction",
"type": "object"
}
]
},
"CommandExecutionStatus": {
"enum": [
"inProgress",
"completed",
"failed",
"declined"
],
"type": "string"
},
"FileUpdateChange": {
"properties": {
"diff": {
"type": "string"
},
"kind": {
"$ref": "#/definitions/PatchChangeKind"
},
"path": {
"type": "string"
}
},
"required": [
"diff",
"kind",
"path"
],
"type": "object"
},
"McpToolCallError": {
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"McpToolCallResult": {
"properties": {
"content": {
"items": true,
"type": "array"
},
"structuredContent": true
},
"required": [
"content"
],
"type": "object"
},
"McpToolCallStatus": {
"enum": [
"inProgress",
"completed",
"failed"
],
"type": "string"
},
"PatchApplyStatus": {
"enum": [
"inProgress",
"completed",
"failed",
"declined"
],
"type": "string"
},
"PatchChangeKind": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"add"
],
"title": "AddPatchChangeKindType",
"type": "string"
}
},
"required": [
"type"
],
"title": "AddPatchChangeKind",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"delete"
],
"title": "DeletePatchChangeKindType",
"type": "string"
}
},
"required": [
"type"
],
"title": "DeletePatchChangeKind",
"type": "object"
},
{
"properties": {
"move_path": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"update"
],
"title": "UpdatePatchChangeKindType",
"type": "string"
}
},
"required": [
"type"
],
"title": "UpdatePatchChangeKind",
"type": "object"
}
]
},
"TextElement": {
"properties": {
"byteRange": {
"allOf": [
{
"$ref": "#/definitions/ByteRange"
}
],
"description": "Byte range in the parent `text` buffer that this element occupies."
},
"placeholder": {
"description": "Optional human-readable placeholder for the element, displayed in the UI.",
"type": [
"string",
"null"
]
}
},
"required": [
"byteRange"
],
"type": "object"
},
"ThreadItem": {
"oneOf": [
{
"properties": {
"content": {
"items": {
"$ref": "#/definitions/UserInput"
},
"type": "array"
},
"id": {
"type": "string"
},
"type": {
"enum": [
"userMessage"
],
"title": "UserMessageThreadItemType",
"type": "string"
}
},
"required": [
"content",
"id",
"type"
],
"title": "UserMessageThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"type": {
"enum": [
"agentMessage"
],
"title": "AgentMessageThreadItemType",
"type": "string"
}
},
"required": [
"id",
"text",
"type"
],
"title": "AgentMessageThreadItem",
"type": "object"
},
{
"description": "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"type": {
"enum": [
"plan"
],
"title": "PlanThreadItemType",
"type": "string"
}
},
"required": [
"id",
"text",
"type"
],
"title": "PlanThreadItem",
"type": "object"
},
{
"properties": {
"content": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"summary": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"type": {
"enum": [
"reasoning"
],
"title": "ReasoningThreadItemType",
"type": "string"
}
},
"required": [
"id",
"type"
],
"title": "ReasoningThreadItem",
"type": "object"
},
{
"properties": {
"aggregatedOutput": {
"description": "The command's output, aggregated from stdout and stderr.",
"type": [
"string",
"null"
]
},
"command": {
"description": "The command to be executed.",
"type": "string"
},
"commandActions": {
"description": "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
"items": {
"$ref": "#/definitions/CommandAction"
},
"type": "array"
},
"cwd": {
"description": "The command's working directory.",
"type": "string"
},
"durationMs": {
"description": "The duration of the command execution in milliseconds.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"exitCode": {
"description": "The command's exit code.",
"format": "int32",
"type": [
"integer",
"null"
]
},
"id": {
"type": "string"
},
"processId": {
"description": "Identifier for the underlying PTY process (when available).",
"type": [
"string",
"null"
]
},
"status": {
"$ref": "#/definitions/CommandExecutionStatus"
},
"type": {
"enum": [
"commandExecution"
],
"title": "CommandExecutionThreadItemType",
"type": "string"
}
},
"required": [
"command",
"commandActions",
"cwd",
"id",
"status",
"type"
],
"title": "CommandExecutionThreadItem",
"type": "object"
},
{
"properties": {
"changes": {
"items": {
"$ref": "#/definitions/FileUpdateChange"
},
"type": "array"
},
"id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/PatchApplyStatus"
},
"type": {
"enum": [
"fileChange"
],
"title": "FileChangeThreadItemType",
"type": "string"
}
},
"required": [
"changes",
"id",
"status",
"type"
],
"title": "FileChangeThreadItem",
"type": "object"
},
{
"properties": {
"arguments": true,
"durationMs": {
"description": "The duration of the MCP tool call in milliseconds.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/definitions/McpToolCallError"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"result": {
"anyOf": [
{
"$ref": "#/definitions/McpToolCallResult"
},
{
"type": "null"
}
]
},
"server": {
"type": "string"
},
"status": {
"$ref": "#/definitions/McpToolCallStatus"
},
"tool": {
"type": "string"
},
"type": {
"enum": [
"mcpToolCall"
],
"title": "McpToolCallThreadItemType",
"type": "string"
}
},
"required": [
"arguments",
"id",
"server",
"status",
"tool",
"type"
],
"title": "McpToolCallThreadItem",
"type": "object"
},
{
"properties": {
"agentsStates": {
"additionalProperties": {
"$ref": "#/definitions/CollabAgentState"
},
"description": "Last known status of the target agents, when available.",
"type": "object"
},
"id": {
"description": "Unique identifier for this collab tool call.",
"type": "string"
},
"prompt": {
"description": "Prompt text sent as part of the collab tool call, when available.",
"type": [
"string",
"null"
]
},
"receiverThreadIds": {
"description": "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
"items": {
"type": "string"
},
"type": "array"
},
"senderThreadId": {
"description": "Thread ID of the agent issuing the collab request.",
"type": "string"
},
"status": {
"allOf": [
{
"$ref": "#/definitions/CollabAgentToolCallStatus"
}
],
"description": "Current status of the collab tool call."
},
"tool": {
"allOf": [
{
"$ref": "#/definitions/CollabAgentTool"
}
],
"description": "Name of the collab tool that was invoked."
},
"type": {
"enum": [
"collabAgentToolCall"
],
"title": "CollabAgentToolCallThreadItemType",
"type": "string"
}
},
"required": [
"agentsStates",
"id",
"receiverThreadIds",
"senderThreadId",
"status",
"tool",
"type"
],
"title": "CollabAgentToolCallThreadItem",
"type": "object"
},
{
"properties": {
"action": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchAction"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"query": {
"type": "string"
},
"type": {
"enum": [
"webSearch"
],
"title": "WebSearchThreadItemType",
"type": "string"
}
},
"required": [
"id",
"query",
"type"
],
"title": "WebSearchThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"path": {
"type": "string"
},
"type": {
"enum": [
"imageView"
],
"title": "ImageViewThreadItemType",
"type": "string"
}
},
"required": [
"id",
"path",
"type"
],
"title": "ImageViewThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"review": {
"type": "string"
},
"type": {
"enum": [
"enteredReviewMode"
],
"title": "EnteredReviewModeThreadItemType",
"type": "string"
}
},
"required": [
"id",
"review",
"type"
],
"title": "EnteredReviewModeThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"review": {
"type": "string"
},
"type": {
"enum": [
"exitedReviewMode"
],
"title": "ExitedReviewModeThreadItemType",
"type": "string"
}
},
"required": [
"id",
"review",
"type"
],
"title": "ExitedReviewModeThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"contextCompaction"
],
"title": "ContextCompactionThreadItemType",
"type": "string"
}
},
"required": [
"id",
"type"
],
"title": "ContextCompactionThreadItem",
"type": "object"
}
]
},
"UserInput": {
"oneOf": [
{
"properties": {
"text": {
"type": "string"
},
"text_elements": {
"default": [],
"description": "UI-defined spans within `text` used to render or persist special elements.",
"items": {
"$ref": "#/definitions/TextElement"
},
"type": "array"
},
"type": {
"enum": [
"text"
],
"title": "TextUserInputType",
"type": "string"
}
},
"required": [
"text",
"type"
],
"title": "TextUserInput",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"image"
],
"title": "ImageUserInputType",
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"type",
"url"
],
"title": "ImageUserInput",
"type": "object"
},
{
"properties": {
"path": {
"type": "string"
},
"type": {
"enum": [
"localImage"
],
"title": "LocalImageUserInputType",
"type": "string"
}
},
"required": [
"path",
"type"
],
"title": "LocalImageUserInput",
"type": "object"
},
{
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"type": {
"enum": [
"skill"
],
"title": "SkillUserInputType",
"type": "string"
}
},
"required": [
"name",
"path",
"type"
],
"title": "SkillUserInput",
"type": "object"
},
{
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"type": {
"enum": [
"mention"
],
"title": "MentionUserInputType",
"type": "string"
}
},
"required": [
"name",
"path",
"type"
],
"title": "MentionUserInput",
"type": "object"
}
]
},
"WebSearchAction": {
"oneOf": [
{
"properties": {
"queries": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"query": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"search"
],
"title": "SearchWebSearchActionType",
"type": "string"
}
},
"required": [
"type"
],
"title": "SearchWebSearchAction",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"openPage"
],
"title": "OpenPageWebSearchActionType",
"type": "string"
},
"url": {
"type": [
"string",
"null"
]
}
},
"required": [
"type"
],
"title": "OpenPageWebSearchAction",
"type": "object"
},
{
"properties": {
"pattern": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"findInPage"
],
"title": "FindInPageWebSearchActionType",
"type": "string"
},
"url": {
"type": [
"string",
"null"
]
}
},
"required": [
"type"
],
"title": "FindInPageWebSearchAction",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"other"
],
"title": "OtherWebSearchActionType",
"type": "string"
}
},
"required": [
"type"
],
"title": "OtherWebSearchAction",
"type": "object"
}
]
}
},
"properties": {
"item": {
"$ref": "#/definitions/ThreadItem"
},
"threadId": {
"type": "string"
},
"turnId": {
"type": "string"
}
},
"required": [
"item",
"threadId",
"turnId"
],
"title": "ItemStartedNotification",
"type": "object"
}