Add initial set of doc comments to the SDK (#4513)

Also perform minor code cleanup.

Author: pakrym-oai

codex-rs/exec/src/exec_events.rs

@@ -2,34 +2,45 @@ use serde::Deserialize;
 use serde::Serialize;
 use ts_rs::TS;
 
-/// Top-level events emitted on the Codex Exec thread stream.
+/// Top-level JSONL events emitted by codex exec
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 #[serde(tag = "type")]
 pub enum ThreadEvent {
+    /// Emitted when a new thread is started as the first event.
     #[serde(rename = "thread.started")]
     ThreadStarted(ThreadStartedEvent),
+    /// Emitted when a turn is started by sending a new prompt to the model.
+    /// A turn encompasses all events that happen while agent is processing the prompt.
     #[serde(rename = "turn.started")]
     TurnStarted(TurnStartedEvent),
+    /// Emitted when a turn is completed. Typically right after the assistant's response.
     #[serde(rename = "turn.completed")]
     TurnCompleted(TurnCompletedEvent),
+    /// Indicates that a turn failed with an error.
     #[serde(rename = "turn.failed")]
     TurnFailed(TurnFailedEvent),
+    /// Emitted when a new item is added to the thread. Typically the item will be in an "in progress" state.
     #[serde(rename = "item.started")]
     ItemStarted(ItemStartedEvent),
+    /// Emitted when an item is updated.
     #[serde(rename = "item.updated")]
     ItemUpdated(ItemUpdatedEvent),
+    /// Signals that an item has reached a terminal state—either success or failure.
     #[serde(rename = "item.completed")]
     ItemCompleted(ItemCompletedEvent),
+    /// Represents an unrecoverable error emitted directly by the event stream.
     #[serde(rename = "error")]
     Error(ThreadErrorEvent),
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct ThreadStartedEvent {
+    /// The identified of the new thread. Can be used to resume the thread later.
     pub thread_id: String,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS, Default)]
+
 pub struct TurnStartedEvent {}
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
@@ -42,11 +53,14 @@ pub struct TurnFailedEvent {
     pub error: ThreadErrorEvent,
 }
 
-/// Minimal usage summary for a turn.
+/// Describes the usage of tokens during a turn.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS, Default)]
 pub struct Usage {
+    /// The number of input tokens used during the turn.
     pub input_tokens: u64,
+    /// The number of cached input tokens used during the turn.
     pub cached_input_tokens: u64,
+    /// The number of output tokens used during the turn.
     pub output_tokens: u64,
 }
 
@@ -83,34 +97,44 @@ pub struct ThreadItem {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 #[serde(tag = "item_type", rename_all = "snake_case")]
 pub enum ThreadItemDetails {
+    /// Response from the agent.
+    /// Either a natural-language response or a JSON string when structured output is requested.
     AssistantMessage(AssistantMessageItem),
+    /// Agent's reasoning summary.
     Reasoning(ReasoningItem),
+    /// Tracks a command executed by the agent. The item starts when the command is
+    /// spawned, and completes when the process exits with an exit code.
     CommandExecution(CommandExecutionItem),
+    /// Represents a set of file changes by the agent. The item is emitted only as a
+    /// completed event once the patch succeeds or fails.
     FileChange(FileChangeItem),
+    /// Represents a call to an MCP tool. The item starts when the invocation is
+    /// dispatched and completes when the MCP server reports success or failure.
     McpToolCall(McpToolCallItem),
+    /// Captures a web search request. It starts when the search is kicked off
+    /// and completes when results are returned to the agent.
     WebSearch(WebSearchItem),
+    /// Tracks the agent's running to-do list. It starts when the plan is first
+    /// issued, updates as steps change state, and completes when the turn ends.
     TodoList(TodoListItem),
+    /// Describes a non-fatal error surfaced as an item.
     Error(ErrorItem),
 }
 
-/// Session metadata.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
-pub struct SessionItem {
-    pub session_id: String,
-}
-
-/// Assistant message payload.
+/// Response from the agent.
+/// Either a natural-language response or a JSON string when structured output is requested.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct AssistantMessageItem {
     pub text: String,
 }
 
-/// Model reasoning summary payload.
+/// Agent's reasoning summary.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct ReasoningItem {
     pub text: String,
 }
 
+/// The status of a command execution.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum CommandExecutionStatus {
@@ -120,7 +144,7 @@ pub enum CommandExecutionStatus {
     Failed,
 }
 
-/// Local shell command execution payload.
+/// A command executed by the agent.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct CommandExecutionItem {
     pub command: String,
@@ -130,28 +154,29 @@ pub struct CommandExecutionItem {
     pub status: CommandExecutionStatus,
 }
 
-/// Single file change summary for a patch.
+/// A set of file changes by the agent.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct FileUpdateChange {
     pub path: String,
     pub kind: PatchChangeKind,
 }
 
+/// The status of a file change.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum PatchApplyStatus {
     Completed,
     Failed,
 }
 
-/// Patch application payload.
+/// A set of file changes by the agent.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct FileChangeItem {
     pub changes: Vec<FileUpdateChange>,
     pub status: PatchApplyStatus,
 }
 
-/// Known change kinds for a patch.
+/// Indicates the type of the file change.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum PatchChangeKind {
@@ -160,6 +185,7 @@ pub enum PatchChangeKind {
     Update,
 }
 
+/// The status of an MCP tool call.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default, TS)]
 #[serde(rename_all = "snake_case")]
 pub enum McpToolCallStatus {
@@ -169,23 +195,27 @@ pub enum McpToolCallStatus {
     Failed,
 }
 
+/// A call to an MCP tool.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct McpToolCallItem {
     pub server: String,
     pub tool: String,
     pub status: McpToolCallStatus,
 }
 
+/// A web search request.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct WebSearchItem {
     pub query: String,
 }
 
+/// An error notification.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct ErrorItem {
     pub message: String,
 }
 
+/// An item in agent's to-do list.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
 pub struct TodoItem {
     pub text: String,

sdk/typescript/README.md

@@ -1 +1,53 @@
 # Codex SDK
+
+Bring the power of the best coding agent to your application.
+
+## Installation
+
+```bash
+npm install @openai/codex-sdk
+```
+
+## Usage
+
+Call `startThread()` and `run()` to start a thead with Codex.
+
+```typescript
+import { Codex } from "@openai/codex-sdk";
+
+const codex = new Codex();
+const thread = codex.startThread();
+const result = await thread.run("Diagnose the test failure and propose a fix");
+
+console.log(result);
+```
+
+You can call `run()` again to continue the same thread.
+
+```typescript
+const result = await thread.run("Implement the fix");
+
+console.log(result);
+```
+
+### Streaming
+
+The `await run()` method completes when a thread turn is complete and agent is prepared the final response.
+
+You can thread items while they are being produced by calling `await runStreamed()`.
+
+```typescript
+const result = thread.runStreamed("Diagnose the test failure and propose a fix");
+```
+
+### Resuming a thread
+
+If you don't have the original `Thread` instance to continue the thread, you can resume a thread by calling `resumeThread()` and providing the thread.
+
+```typescript
+const threadId = "...";
+const thread = codex.resumeThread(threadId);
+const result = await thread.run("Implement the fix");
+
+console.log(result);
+```

sdk/typescript/src/codex.ts

@@ -2,6 +2,11 @@ import { CodexOptions } from "./codexOptions";
 import { CodexExec } from "./exec";
 import { Thread } from "./thread";
 
+/**
+ * Codex is the main class for interacting with the Codex agent.
+ *
+ * Use the `startThread()` method to start a new thread or `resumeThread()` to resume a previously started thread.
+ */
 export class Codex {
   private exec: CodexExec;
   private options: CodexOptions;
@@ -11,10 +16,21 @@ export class Codex {
     this.options = options;
   }
 
+  /**
+   * Starts a new conversation with an agent.
+   * @returns A new thread instance.
+   */
   startThread(): Thread {
     return new Thread(this.exec, this.options);
   }
 
+  /**
+   * Resumes a conversation with an agent based on the thread id.
+   * Threads are persisted in ~/.codex/sessions.
+   *
+   * @param id The id of the thread to resume.
+   * @returns A new thread instance.
+   */
   resumeThread(id: string): Thread {
     return new Thread(this.exec, this.options, id);
   }

sdk/typescript/src/events.ts

@@ -2,55 +2,73 @@
 
 import type { ThreadItem } from "./items";
 
+/** Emitted when a new thread is started as the first event. */
 export type ThreadStartedEvent = {
   type: "thread.started";
+  /** The identifier of the new thread. Can be used to resume the thread later. */
   thread_id: string;
 };
 
+/**
+ * Emitted when a turn is started by sending a new prompt to the model.
+ * A turn encompasses all events that happen while the agent is processing the prompt.
+ */
 export type TurnStartedEvent = {
   type: "turn.started";
 };
 
+/** Describes the usage of tokens during a turn. */
 export type Usage = {
+  /** The number of input tokens used during the turn. */
   input_tokens: number;
+  /** The number of cached input tokens used during the turn. */
   cached_input_tokens: number;
+  /** The number of output tokens used during the turn. */
   output_tokens: number;
 };
 
+/** Emitted when a turn is completed. Typically right after the assistant's response. */
 export type TurnCompletedEvent = {
   type: "turn.completed";
   usage: Usage;
 };
 
+/** Indicates that a turn failed with an error. */
 export type TurnFailedEvent = {
   type: "turn.failed";
   error: ThreadError;
 };
 
+/** Emitted when a new item is added to the thread. Typically the item is initially "in progress". */
 export type ItemStartedEvent = {
   type: "item.started";
   item: ThreadItem;
 };
 
+/** Emitted when an item is updated. */
 export type ItemUpdatedEvent = {
   type: "item.updated";
   item: ThreadItem;
 };
 
+/** Signals that an item has reached a terminal state—either success or failure. */
 export type ItemCompletedEvent = {
   type: "item.completed";
   item: ThreadItem;
 };
 
+/** Fatal error emitted by the stream. */
 export type ThreadError = {
   message: string;
 };
 
+/** Represents an unrecoverable error emitted directly by the event stream. */
 export type ThreadErrorEvent = {
   type: "error";
   message: string;
 };
 
+/** Top-level JSONL events emitted by codex exec. */
 export type ThreadEvent =
   | ThreadStartedEvent
   | TurnStartedEvent

sdk/typescript/src/index.ts

@@ -22,7 +22,8 @@ export type {
   ErrorItem,
 } from "./items";
 
-export { Thread, RunResult, RunStreamedResult, Input } from "./thread";
+export { Thread } from "./thread";
+export type { RunResult, RunStreamedResult, Input } from "./thread";
 
 export { Codex } from "./codex";