Skip to main content
Response types define the structure of responses sent from agent to client in reply to requests.

​
Initialization Responses

​
InitializeResponse

Response to the initialize method containing negotiated protocol version and agent capabilities. 
export type InitializeResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Capabilities supported by the agent.
   */
  agentCapabilities?: AgentCapabilities;
  /**
   * Information about the Agent name and version sent to the Client.
   */
  agentInfo?: Implementation | null;
  /**
   * Authentication methods supported by the agent.
   */
  authMethods?: Array<AuthMethod>;
  /**
   * The protocol version the client specified if supported by the agent,
   * or the latest protocol version supported by the agent.
   */
  protocolVersion: ProtocolVersion;
};
See also: InitializeRequest

​
AuthenticateResponse

Response to the authenticate method. 
export type AuthenticateResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
Session Management Responses

​
NewSessionResponse

Response from creating a new session. 
export type NewSessionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Initial session configuration options if supported by the Agent.
   */
  configOptions?: Array<SessionConfigOption> | null;
  /**
   * Initial model state if supported by the Agent (UNSTABLE)
   */
  models?: SessionModelState | null;
  /**
   * Initial mode state if supported by the Agent
   */
  modes?: SessionModeState | null;
  /**
   * Unique identifier for the created session.
   */
  sessionId: SessionId;
};
See also: NewSessionRequest

​
LoadSessionResponse

Response from loading an existing session. 
export type LoadSessionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Initial session configuration options if supported by the Agent.
   */
  configOptions?: Array<SessionConfigOption> | null;
  /**
   * Initial model state if supported by the Agent (UNSTABLE)
   */
  models?: SessionModelState | null;
  /**
   * Initial mode state if supported by the Agent
   */
  modes?: SessionModeState | null;
};

​
ListSessionsResponse

UNSTABLE - Response from listing sessions. 
export type ListSessionsResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Opaque cursor token. If present, pass this in the next request's cursor parameter
   * to fetch the next page. If absent, there are no more results.
   */
  nextCursor?: string | null;
  /**
   * Array of session information objects
   */
  sessions: Array<SessionInfo>;
};

​
ForkSessionResponse

UNSTABLE - Response from forking an existing session. 
export type ForkSessionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Initial session configuration options if supported by the Agent.
   */
  configOptions?: Array<SessionConfigOption> | null;
  /**
   * Initial model state if supported by the Agent (UNSTABLE)
   */
  models?: SessionModelState | null;
  /**
   * Initial mode state if supported by the Agent
   */
  modes?: SessionModeState | null;
  /**
   * Unique identifier for the newly created forked session.
   */
  sessionId: SessionId;
};

​
ResumeSessionResponse

UNSTABLE - Response from resuming a stopped session. 
export type ResumeSessionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
StopSessionResponse

UNSTABLE - Response from stopping a running session. 
export type StopSessionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The reason the session was stopped.
   */
  stopReason: StopReason;
};

​
Prompt Responses

​
PromptResponse

Response to a prompt request. The agent streams updates via SessionUpdate notifications during processing. 
export type PromptResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};
See also: PromptRequest, SessionUpdate

​
Configuration Responses

​
SetSessionModeResponse

Response to changing the session mode. 
export type SetSessionModeResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
SetSessionConfigOptionResponse

Response to updating a session configuration option. 
export type SetSessionConfigOptionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
SetSessionModelResponse

UNSTABLE - Response to changing the session model. 
export type SetSessionModelResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
File System Responses

These responses are sent from client to agent.

​
ReadTextFileResponse

Response containing the contents of the requested file. 
export type ReadTextFileResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The text content of the file.
   */
  content: string;
};

​
WriteTextFileResponse

Response confirming the file was written. 
export type WriteTextFileResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
RequestPermissionResponse

Response containing the user’s permission decision. 
export type RequestPermissionResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The outcome of the permission request.
   */
  outcome: RequestPermissionOutcome;
};
The RequestPermissionOutcome type is a union: 
export type RequestPermissionOutcome =
  | (SelectedPermissionOutcome & {
      type: "selected";
    })
  | { type: "timeout" }
  | { type: "cancelled" };

export type SelectedPermissionOutcome = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the permission option the user selected.
   */
  optionId: PermissionOptionId;
};

​
Terminal Responses

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

​
CreateTerminalResponse

Response containing the ID of the created terminal. 
export type CreateTerminalResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The unique identifier for the created terminal.
   */
  terminalId: string;
};

​
TerminalOutputResponse

Response containing the current terminal state and output. 
export type TerminalOutputResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Information about the terminal.
   */
  terminal: Terminal;
};
The Terminal type includes: 
export type Terminal = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Optional exit status if the terminal has exited.
   */
  exitStatus?: TerminalExitStatus | null;
  /**
   * Current output from the terminal.
   */
  output: string;
  /**
   * The terminal ID.
   */
  terminalId: string;
};

export type TerminalExitStatus = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The exit code from the terminal process.
   */
  code: number;
};

​
ReleaseTerminalResponse

Response confirming the terminal was released. 
export type ReleaseTerminalResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
WaitForTerminalExitResponse

Response containing the terminal’s exit status. 
export type WaitForTerminalExitResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The exit status of the terminal.
   */
  exitStatus: TerminalExitStatus;
};

​
KillTerminalResponse

Response confirming the terminal was killed. 
export type KillTerminalResponse = {
  _meta?: {
    [key: string]: unknown;
  } | null;
};

​
Error Responses

All requests may return an error response instead of a success response: 
export type AgentResponse =
  | {
      id: RequestId;
      result: /* ... success types ... */;
    }
  | {
      error: Error;
      id: RequestId;
    };

export type Error = {
  /**
   * Authentication methods relevant to this error (UNSTABLE)
   */
  authMethods?: Array<AuthMethod>;
  /**
   * A number indicating the error type that occurred.
   */
  code: ErrorCode;
  /**
   * Optional additional information about the error.
   */
  data?: unknown;
  /**
   * A string providing a short description of the error.
   */
  message: string;
};
Common error codes: 
export type ErrorCode =
  | -32700 // Parse error
  | -32600 // Invalid request
  | -32601 // Method not found
  | -32602 // Invalid params
  | -32603 // Internal error
  | -32800 // Unauthorized
  | -32000 // Server error
  | -32002 // Request cancelled
  | number; // Custom error codes

Build docs developers (and LLMs) love

Get started for freeTalk to us