> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Types

> Request types for client-to-agent communication

Request types define the structure of requests sent from client to agent. All requests expect a corresponding response.

## Initialization Requests

### InitializeRequest

Sent by the client to establish connection and negotiate capabilities.

```typescript theme={null}
export type InitializeRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Capabilities supported by the client.
   */
  clientCapabilities?: ClientCapabilities;
  /**
   * Information about the Client name and version sent to the Agent.
   */
  clientInfo?: Implementation | null;
  /**
   * The latest protocol version supported by the client.
   */
  protocolVersion: ProtocolVersion;
};
```

**See also:** [InitializeResponse](/api/response-types#initializeresponse)

### AuthenticateRequest

Specifies which authentication method to use.

```typescript theme={null}
export type AuthenticateRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the authentication method to use.
   * Must be one of the methods advertised in the initialize response.
   */
  methodId: string;
};
```

## Session Management Requests

### NewSessionRequest

Creates a new agent session.

```typescript theme={null}
export type NewSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The working directory for this session. Must be an absolute path.
   */
  cwd: string;
  /**
   * List of MCP (Model Context Protocol) servers the agent should connect to.
   */
  mcpServers: Array<McpServer>;
};
```

**See also:** [NewSessionResponse](/api/response-types#newsessionresponse)

### LoadSessionRequest

Loads an existing session. Only available if the agent supports the `loadSession` capability.

```typescript theme={null}
export type LoadSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The working directory for this session.
   */
  cwd: string;
  /**
   * List of MCP servers to connect to for this session.
   */
  mcpServers: Array<McpServer>;
  /**
   * The ID of the session to load.
   */
  sessionId: SessionId;
};
```

### ListSessionsRequest

**UNSTABLE** - Lists existing sessions with optional filtering and pagination.

```typescript theme={null}
export type ListSessionsRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
   */
  cursor?: string | null;
  /**
   * Filter sessions by working directory. Must be an absolute path.
   */
  cwd?: string | null;
};
```

### ForkSessionRequest

**UNSTABLE** - Creates a new session based on the context of an existing one.

```typescript theme={null}
export type ForkSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The working directory for this session.
   */
  cwd: string;
  /**
   * List of MCP servers to connect to for this session.
   */
  mcpServers?: Array<McpServer>;
  /**
   * The ID of the session to fork.
   */
  sessionId: SessionId;
};
```

### ResumeSessionRequest

**UNSTABLE** - Resumes a stopped session.

```typescript theme={null}
export type ResumeSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the session to resume.
   */
  sessionId: SessionId;
};
```

### StopSessionRequest

**UNSTABLE** - Stops a running session.

```typescript theme={null}
export type StopSessionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the session to stop.
   */
  sessionId: SessionId;
};
```

## Prompt Requests

### PromptRequest

Sends a prompt to the agent for processing.

```typescript theme={null}
export type PromptRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Optional command to execute (e.g., 'create_plan', 'research_codebase').
   */
  command?: string | null;
  /**
   * Optional input parameter for the command if required.
   */
  commandInput?: string | null;
  /**
   * The prompt content blocks to send to the agent.
   */
  prompt: Array<Content>;
  /**
   * The ID of the session to send the prompt to.
   */
  sessionId: SessionId;
};
```

**See also:** [PromptResponse](/api/response-types#promptresponse), [SessionUpdate](/api/notification-types#sessionupdate)

## Configuration Requests

### SetSessionModeRequest

Changes the session's operating mode.

```typescript theme={null}
export type SetSessionModeRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the mode to switch to.
   */
  modeId: SessionModeId;
  /**
   * The ID of the session.
   */
  sessionId: SessionId;
};
```

### SetSessionConfigOptionRequest

Updates a session configuration option.

```typescript theme={null}
export type SetSessionConfigOptionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the configuration option to set.
   */
  configId: SessionConfigId;
  /**
   * The ID of the session.
   */
  sessionId: SessionId;
  /**
   * The new value for the configuration option.
   */
  value: SessionConfigValueId;
};
```

### SetSessionModelRequest

**UNSTABLE** - Changes the model used by the session.

```typescript theme={null}
export type SetSessionModelRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the model to use.
   */
  modelId: ModelId;
  /**
   * The ID of the session.
   */
  sessionId: SessionId;
};
```

## File System Requests

These requests are sent from agent to client.

### ReadTextFileRequest

Requests the client to read a text file.

```typescript theme={null}
export type ReadTextFileRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Absolute path to the file to read.
   */
  path: string;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};
```

### WriteTextFileRequest

Requests the client to write a text file.

```typescript theme={null}
export type WriteTextFileRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The text content to write to the file.
   */
  content: string;
  /**
   * Absolute path to the file to write.
   */
  path: string;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};
```

### RequestPermissionRequest

Requests the user to choose from a set of permission options.

```typescript theme={null}
export type RequestPermissionRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Optional additional context about why permission is needed.
   */
  context?: string | null;
  /**
   * The permission options to present to the user.
   */
  options: Array<PermissionOption>;
  /**
   * Human-readable prompt to display to the user.
   */
  prompt: string;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};
```

## Terminal Requests

These requests are sent from agent to client for terminal operations.

### CreateTerminalRequest

Creates a new terminal and executes a command.

```typescript theme={null}
export type CreateTerminalRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Array of command arguments.
   */
  args?: Array<string>;
  /**
   * The command to execute.
   */
  command: string;
  /**
   * Working directory for the command (absolute path).
   */
  cwd?: string | null;
  /**
   * Environment variables for the command.
   */
  env?: Array<EnvVariable>;
  /**
   * Maximum number of output bytes to retain.
   */
  outputByteLimit?: number | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
};
```

### TerminalOutputRequest

Requests the current output from a terminal.

```typescript theme={null}
export type TerminalOutputRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal.
   */
  terminalId: string;
};
```

### ReleaseTerminalRequest

Releases a terminal when no longer needed.

```typescript theme={null}
export type ReleaseTerminalRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal to release.
   */
  terminalId: string;
};
```

### WaitForTerminalExitRequest

Waits for a terminal to exit.

```typescript theme={null}
export type WaitForTerminalExitRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal to wait for.
   */
  terminalId: string;
};
```

### KillTerminalRequest

Kills a terminal without releasing it.

```typescript theme={null}
export type KillTerminalRequest = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The session ID for this request.
   */
  sessionId: SessionId;
  /**
   * The ID of the terminal to kill.
   */
  terminalId: string;
};
```