Response Types

Response types for agent-to-client communication

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