or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

agent-connection.mdclient-connection.mderrors.mdindex.mdinterfaces.mdprotocol-types.mdstream.md
tile.json

protocol-types.mddocs/

Protocol Types

This document provides a comprehensive reference of all TypeScript types used in the ACP protocol, including request/response interfaces, capability definitions, content types, and utility types.

Table of Contents

  • Initialization Types
  • Session Management Types
  • Prompt Types
  • File System Types
  • Terminal Types
  • Permission Types
  • Content Types
  • Capability Types
  • MCP Types
  • Utility Types

Initialization Types

InitializeRequest

interface InitializeRequest {
  protocolVersion: number;
  clientCapabilities?: ClientCapabilities;
  clientInfo?: Implementation;
  _meta?: Record<string, unknown>;
}

Establishes connection and negotiates capabilities between client and agent.

InitializeResponse

interface InitializeResponse {
  protocolVersion: number;
  agentCapabilities?: AgentCapabilities;
  agentInfo?: Implementation;
  authMethods?: AuthMethod[];
  _meta?: Record<string, unknown>;
}

Agent's response containing its capabilities and optional authentication methods.

Implementation

interface Implementation {
  name: string;
  version: string;
  title?: string;
}

Information about an implementation (client or agent).

AuthMethod

interface AuthMethod {
  id: string;
  name: string;
  description?: string;
}

Available authentication method advertised by the agent.

AuthenticateRequest

interface AuthenticateRequest {
  methodId: string;
  _meta?: Record<string, unknown>;
}

Request to authenticate using a specific method. The methodId must be one of the method IDs advertised in the initialize response's authMethods array.

AuthenticateResponse

interface AuthenticateResponse {
  _meta?: Record<string, unknown>;
}

Response to authentication (typically empty on success).

Session Management Types

NewSessionRequest

interface NewSessionRequest {
  cwd: string;
  mcpServers: McpServer[];
  _meta?: Record<string, unknown>;
}

Creates a new conversation session with specified MCP servers. The cwd parameter specifies the working directory for the session and must be an absolute path.

NewSessionResponse

interface NewSessionResponse {
  sessionId: string;
  modes?: SessionModeState;
  models?: SessionModelState;
  _meta?: Record<string, unknown>;
}

Response containing session ID and available modes.

LoadSessionRequest

interface LoadSessionRequest {
  sessionId: string;
  cwd: string;
  mcpServers: McpServer[];
  _meta?: Record<string, unknown>;
}

Loads an existing session to resume conversation.

LoadSessionResponse

interface LoadSessionResponse {
  modes?: SessionModeState;
  models?: SessionModelState;
  _meta?: Record<string, unknown>;
}

Response when loading a session (agent will stream history via notifications).

SessionMode

interface SessionMode {
  id: SessionModeId;
  name: string;
  description?: string;
}

Represents an operational mode the agent can operate in.

SessionModeId

type SessionModeId = string;

Identifier for a session mode (e.g., "code", "ask", "architect").

SessionModeState

interface SessionModeState {
  availableModes: SessionMode[];
  currentModeId: string;
  _meta?: Record<string, unknown>;
}

Set of available modes and the currently active one.

SetSessionModeRequest

interface SetSessionModeRequest {
  sessionId: string;
  modeId: string;
  _meta?: Record<string, unknown>;
}

Request to change the session's operational mode.

SetSessionModeResponse

interface SetSessionModeResponse {
  _meta?: Record<string, unknown>;
}

Response to mode change (typically empty).

SessionModelState

UNSTABLE - May change or be removed.

interface SessionModelState {
  availableModels: ModelInfo[];
  currentModelId: string;
  _meta?: Record<string, unknown>;
}

Set of available models and the currently active one.

ModelInfo

UNSTABLE - May change or be removed.

interface ModelInfo {
  modelId: string;
  name: string;
  description?: string;
  _meta?: Record<string, unknown>;
}

Information about a selectable model.

SetSessionModelRequest

UNSTABLE - May change or be removed.

interface SetSessionModelRequest {
  sessionId: string;
  modelId: string;
  _meta?: Record<string, unknown>;
}

Request to change the session's model.

SetSessionModelResponse

UNSTABLE - May change or be removed.

interface SetSessionModelResponse {
  _meta?: Record<string, unknown>;
}

Prompt Types

PromptRequest

interface PromptRequest {
  sessionId: string;
  prompt: ContentBlock[];
  _meta?: Record<string, unknown>;
}

Request to process a user prompt.

Role

type Role = "assistant" | "user";

Message role in a conversation (used in annotations audience field).

PromptResponse

interface PromptResponse {
  stopReason: "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
  _meta?: Record<string, unknown>;
}

Response when prompt processing completes.

CancelNotification

interface CancelNotification {
  sessionId: string;
  _meta?: Record<string, unknown>;
}

Notification to cancel ongoing operations for a session.

SessionNotification

interface SessionNotification {
  sessionId: string;
  update:
    | { sessionUpdate: "user_message_chunk"; content: ContentBlock; _meta?: Record<string, unknown> }
    | { sessionUpdate: "agent_message_chunk"; content: ContentBlock; _meta?: Record<string, unknown> }
    | { sessionUpdate: "agent_thought_chunk"; content: ContentBlock; _meta?: Record<string, unknown> }
    | { sessionUpdate: "tool_call"; toolCallId: string; title: string; status?: ToolCallStatus; kind?: ToolKind; content?: ToolCallContent[]; locations?: ToolCallLocation[]; rawInput?: Record<string, unknown>; rawOutput?: Record<string, unknown>; _meta?: Record<string, unknown> }
    | { sessionUpdate: "tool_call_update"; toolCallId: string; title?: string; status?: ToolCallStatus; kind?: ToolKind; content?: ToolCallContent[]; locations?: ToolCallLocation[]; rawInput?: Record<string, unknown>; rawOutput?: Record<string, unknown>; _meta?: Record<string, unknown> }
    | { sessionUpdate: "plan"; entries: PlanEntry[]; _meta?: Record<string, unknown> }
    | { sessionUpdate: "available_commands_update"; availableCommands: AvailableCommand[]; _meta?: Record<string, unknown> }
    | { sessionUpdate: "current_mode_update"; currentModeId: string; _meta?: Record<string, unknown> };
  _meta?: Record<string, unknown>;
}

Notification sent by agent to report session progress. The structure varies based on the update.sessionUpdate field:

  • user_message_chunk: Contains content: ContentBlock for streaming user message content
  • agent_message_chunk: Contains content: ContentBlock for streaming agent message content
  • agent_thought_chunk: Contains content: ContentBlock for streaming agent thought content
  • tool_call: Contains tool call details with toolCallId, title, status, kind, etc.
  • tool_call_update: Contains partial updates to existing tool call
  • plan: Contains entries: PlanEntry[] for execution plan
  • available_commands_update: Contains availableCommands: AvailableCommand[]
  • current_mode_update: Contains currentModeId: string

PlanEntry

interface PlanEntry {
  content: string;
  priority: "high" | "medium" | "low";
  status: "pending" | "in_progress" | "completed";
  _meta?: Record<string, unknown>;
}

Single step in an execution plan.

AvailableCommand

interface AvailableCommand {
  name: string;
  description: string;
  input?: AvailableCommandInput;
  _meta?: Record<string, unknown>;
}

Information about an available command.

AvailableCommandInput

type AvailableCommandInput = UnstructuredCommandInput;

UnstructuredCommandInput

interface UnstructuredCommandInput {
  hint: string;
}

Represents unstructured text input for commands.

File System Types

ReadTextFileRequest

interface ReadTextFileRequest {
  sessionId: string;
  path: string;
  line?: number;
  limit?: number;
  _meta?: Record<string, unknown>;
}

Request to read content from a text file. line is 1-based starting line number, limit is maximum number of lines to read.

ReadTextFileResponse

interface ReadTextFileResponse {
  content: string;
  _meta?: Record<string, unknown>;
}

Response containing file contents.

WriteTextFileRequest

interface WriteTextFileRequest {
  sessionId: string;
  path: string;
  content: string;
  _meta?: Record<string, unknown>;
}

Request to write content to a text file.

WriteTextFileResponse

interface WriteTextFileResponse {
  _meta?: Record<string, unknown>;
}

Response to file write (typically empty).

Terminal Types

CreateTerminalRequest

interface CreateTerminalRequest {
  sessionId: string;
  command: string;
  args?: string[];
  env?: EnvVariable[];
  cwd?: string;
  outputByteLimit?: number;
  _meta?: Record<string, unknown>;
}

Request to create a new terminal and execute a command. outputByteLimit specifies maximum number of output bytes to retain.

CreateTerminalResponse

interface CreateTerminalResponse {
  terminalId: string;
}

Response containing the terminal ID.

TerminalOutputRequest

interface TerminalOutputRequest {
  sessionId: string;
  terminalId: string;
}

Request to get current terminal output.

TerminalOutputResponse

interface TerminalOutputResponse {
  output: string;
  exitStatus?: TerminalExitStatus;
  truncated: boolean;
  _meta?: Record<string, unknown>;
}

Response containing terminal output and optional exit status. truncated indicates whether output was truncated due to byte limits.

TerminalExitStatus

interface TerminalExitStatus {
  exitCode?: number;
  signal?: string;
  _meta?: Record<string, unknown>;
}

Exit status of a terminal command.

WaitForTerminalExitRequest

interface WaitForTerminalExitRequest {
  sessionId: string;
  terminalId: string;
}

Request to wait for terminal command to exit.

WaitForTerminalExitResponse

interface WaitForTerminalExitResponse {
  exitCode?: number;
  signal?: string;
  _meta?: Record<string, unknown>;
}

Response containing exit status.

KillTerminalCommandRequest

interface KillTerminalCommandRequest {
  sessionId: string;
  terminalId: string;
}

Request to kill a terminal command without releasing it.

KillTerminalResponse

interface KillTerminalResponse {
  _meta?: Record<string, unknown>;
}

Response to terminal kill (typically empty).

ReleaseTerminalRequest

interface ReleaseTerminalRequest {
  sessionId: string;
  terminalId: string;
}

Request to release a terminal and free resources.

ReleaseTerminalResponse

interface ReleaseTerminalResponse {
  _meta?: Record<string, unknown>;
}

Response to terminal release (typically empty).

EnvVariable

interface EnvVariable {
  name: string;
  value: string;
  _meta?: Record<string, unknown>;
}

Environment variable for terminal or MCP server.

Permission Types

RequestPermissionRequest

interface RequestPermissionRequest {
  sessionId: string;
  options: PermissionOption[];
  toolCall: {
    toolCallId: string;
    title?: string;
    status?: ToolCallStatus;
    kind?: ToolKind;
    content?: ToolCallContent[];
    locations?: ToolCallLocation[];
    rawInput?: Record<string, unknown>;
    rawOutput?: Record<string, unknown>;
    _meta?: Record<string, unknown>;
  };
  _meta?: Record<string, unknown>;
}

Request for user permission before executing a sensitive operation.

RequestPermissionResponse

interface RequestPermissionResponse {
  outcome:
    | { outcome: "cancelled" }
    | { outcome: "selected"; optionId: string };
  _meta?: Record<string, unknown>;
}

User's permission decision.

PermissionOption

interface PermissionOption {
  optionId: string;
  name: string;
  kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
  _meta?: Record<string, unknown>;
}

An option presented when requesting permission.

Content Types

ContentBlock

type ContentBlock =
  | {
      type: "text";
      text: string;
      annotations?: Annotations;
      _meta?: Record<string, unknown>;
    }
  | {
      type: "image";
      data: string;
      mimeType: string;
      uri?: string;
      annotations?: Annotations;
      _meta?: Record<string, unknown>;
    }
  | {
      type: "audio";
      data: string;
      mimeType: string;
      annotations?: Annotations;
      _meta?: Record<string, unknown>;
    }
  | {
      type: "resource_link";
      uri: string;
      annotations?: Annotations;
      _meta?: Record<string, unknown>;
    }
  | {
      type: "resource";
      uri: string;
      mimeType?: string;
      text?: string;
      blob?: string;
      annotations?: Annotations;
      _meta?: Record<string, unknown>;
    };

Content blocks representing displayable information (text, image, audio, resources).

Annotations

interface Annotations {
  audience?: Role[];
  lastModified?: string;
  priority?: number;
  _meta?: Record<string, unknown>;
}

Optional annotations for content blocks.

ToolCallContent

type ToolCallContent =
  | {
      type: "content";
      content: ContentBlock;
    }
  | {
      type: "diff";
      path: string;
      oldText?: string;
      newText: string;
      _meta?: Record<string, unknown>;
    }
  | {
      type: "terminal";
      terminalId: string;
    };

Content produced by a tool call (content blocks, file diffs, or terminal references).

Tool Call Types

// Tool call status in session updates
type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed";

// Tool operation kind
type ToolKind =
  | "read"
  | "edit"
  | "delete"
  | "move"
  | "search"
  | "execute"
  | "think"
  | "fetch"
  | "switch_mode"
  | "other";

ToolCallLocation

interface ToolCallLocation {
  path: string;
  line?: number;
  _meta?: Record<string, unknown>;
}

A file location being accessed or modified by a tool call.

Resource Types

interface TextResourceContents {
  uri: string;
  mimeType?: string;
  text: string;
  _meta?: Record<string, unknown>;
}

interface BlobResourceContents {
  uri: string;
  mimeType?: string;
  blob: string;
  _meta?: Record<string, unknown>;
}

type EmbeddedResourceResource = TextResourceContents | BlobResourceContents;

Resource content types for embedded resources.

Capability Types

ClientCapabilities

interface ClientCapabilities {
  fs?: FileSystemCapability;
  terminal?: boolean;
  _meta?: Record<string, unknown>;
}

Capabilities supported by the client.

FileSystemCapability

interface FileSystemCapability {
  readTextFile?: boolean;
  writeTextFile?: boolean;
  _meta?: Record<string, unknown>;
}

File system capabilities.

AgentCapabilities

interface AgentCapabilities {
  loadSession?: boolean;
  mcpCapabilities?: McpCapabilities;
  promptCapabilities?: PromptCapabilities;
  _meta?: Record<string, unknown>;
}

Capabilities supported by the agent.

McpCapabilities

interface McpCapabilities {
  http?: boolean;
  sse?: boolean;
  _meta?: Record<string, unknown>;
}

MCP transport capabilities (HTTP and Server-Sent Events).

PromptCapabilities

interface PromptCapabilities {
  image?: boolean;
  audio?: boolean;
  embeddedContext?: boolean;
  _meta?: Record<string, unknown>;
}

Prompt content type capabilities.

MCP Types

McpServer

type McpServer =
  | {
      type: "http";
      name: string;
      url: string;
      headers: HttpHeader[];
    }
  | {
      type: "sse";
      name: string;
      url: string;
      headers: HttpHeader[];
    }
  | {
      name: string;
      command: string;
      args: string[];
      env: EnvVariable[];
    };

MCP server connection configuration (HTTP, SSE, or Stdio).

HttpHeader

interface HttpHeader {
  name: string;
  value: string;
  _meta?: Record<string, unknown>;
}

HTTP header for MCP server requests.

Stdio

interface Stdio {
  name: string;
  command: string;
  args: string[];
  env: EnvVariable[];
}

Stdio transport configuration for MCP.

Utility Types

Extension Types

// Extension method request (agent to client)
interface ExtMethodRequest {
  [key: string]: unknown;
}

// Extension method response (client to agent)
interface ExtMethodResponse {
  [key: string]: unknown;
}

// Extension notification (agent to client)
interface ExtNotification {
  [key: string]: unknown;
}

JSON-RPC Types

// JSON-RPC request
interface Request {
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: unknown;
}

// JSON-RPC notification (no id)
interface Notification {
  jsonrpc: "2.0";
  method: string;
  params?: unknown;
}

// JSON-RPC error
interface Error {
  code: number;
  message: string;
  data?: unknown;
}

// JSON-RPC response
type Response =
  | {
      jsonrpc: "2.0";
      id: string | number | null;
      result: unknown;
    }
  | {
      jsonrpc: "2.0";
      id: string | number | null;
      error: Error;
    };

Message Union Types

// All possible messages from agent
type AgentOutgoingMessage = Request | Response | Notification;

// All possible messages from client
type ClientOutgoingMessage = Request | Response | Notification;

// Union of all message types
type AnyMessage = AgentOutgoingMessage | ClientOutgoingMessage;

Constants

// Protocol version
const PROTOCOL_VERSION: number = 1;

// Agent method names
const AGENT_METHODS = {
  authenticate: "authenticate",
  initialize: "initialize",
  session_cancel: "session/cancel",
  session_load: "session/load",
  session_new: "session/new",
  session_prompt: "session/prompt",
  session_set_mode: "session/set_mode",
  session_set_model: "session/set_model",
} as const;

// Client method names
const CLIENT_METHODS = {
  fs_read_text_file: "fs/read_text_file",
  fs_write_text_file: "fs/write_text_file",
  session_request_permission: "session/request_permission",
  session_update: "session/update",
  terminal_create: "terminal/create",
  terminal_kill: "terminal/kill",
  terminal_output: "terminal/output",
  terminal_release: "terminal/release",
  terminal_wait_for_exit: "terminal/wait_for_exit",
} as const;

Usage Examples

Type-Safe Request/Response

import type {
  InitializeRequest,
  InitializeResponse,
  NewSessionRequest,
  NewSessionResponse
} from '@agentclientprotocol/sdk';

// Type-safe initialization
const initRequest: InitializeRequest = {
  protocolVersion: 1,
  clientCapabilities: {
    fs: { readTextFile: true, writeTextFile: true },
    terminal: true
  },
  clientInfo: {
    name: 'my-client',
    version: '1.0.0'
  }
};

const initResponse: InitializeResponse = await connection.initialize(initRequest);

// Type-safe session creation
const sessionRequest: NewSessionRequest = {
  cwd: '/path/to/project',
  mcpServers: []
};

const sessionResponse: NewSessionResponse = await connection.newSession(sessionRequest);

Type Guards

import type { SessionNotification, ContentBlock } from '@agentclientprotocol/sdk';

function handleSessionUpdate(notification: SessionNotification) {
  switch (notification.update.sessionUpdate) {
    case 'agent_message_chunk':
      // TypeScript knows update has 'content' field
      if (notification.update.content.type === 'text') {
        console.log(notification.update.content.text);
      }
      break;

    case 'tool_call':
      // TypeScript knows update has 'toolCallId' and 'title' fields
      console.log('Tool:', notification.update.title);
      break;

    case 'plan':
      // TypeScript knows update has 'entries' field
      notification.update.entries.forEach(entry => {
        console.log(`${entry.status === 'completed' ? '✓' : '○'} ${entry.content}`);
      });
      break;
  }
}

Notes

  • All types are fully exported from the package
  • Types are validated at runtime using Zod schemas
  • Optional fields are marked with ?
  • Union types use TypeScript discriminated unions for type safety
  • Extension methods/notifications use generic object types
  • All timestamps use ISO 8601 format
  • URIs use standard URI format (e.g., file://, http://)