> ## 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.

# Sessions

> Understanding session lifecycle and state management in ACP

Sessions are independent conversation contexts in ACP. Each session maintains its own history, state, and configuration, allowing multiple parallel conversations with an agent.

## What are Sessions?

A **session** represents a distinct conversation between a user and an agent. Sessions provide:

* **Independent Context** - Each session has its own conversation history
* **Isolated State** - Configuration and mode changes don't affect other sessions
* **Persistent Identity** - Sessions can be saved, loaded, and resumed
* **MCP Connections** - Each session connects to its own set of MCP servers

<Info>
  Think of sessions like browser tabs - each is independent but part of the same application.
</Info>

## Session Lifecycle

Sessions progress through several states:

```mermaid theme={null}
stateDiagram-v2
    [*] --> New: session/new
    [*] --> Loaded: session/load
    [*] --> Resumed: session/resume
    
    New --> Active: First prompt
    Loaded --> Active: Continue conversation
    Resumed --> Active: Continue conversation
    
    Active --> Active: More prompts
    Active --> Forked: session/fork
    Active --> Saved: Save state
    
    Forked --> Active: Work in fork
    Saved --> Loaded: Load later
    Active --> [*]: End session
```

## Creating Sessions

### New Sessions

Create a new session with `session/new`:

```typescript src/acp.ts theme={null}
const session = await agent.newSession({
  cwd: "/path/to/project",
  mcpServers: [
    {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  ]
});

console.log(session.sessionId); // "session-abc123"
console.log(session.availableModes); // [{ id: "code", name: "Code" }, ...]
```

<Note>
  The agent returns a unique `sessionId` that must be included in all subsequent requests for this session.
</Note>

### Session ID Format

```typescript src/schema/types.gen.ts theme={null}
export type SessionId = string;
```

Session IDs are opaque strings generated by the agent. Clients should treat them as opaque identifiers.

## Loading Sessions

Load an existing session to restore conversation history:

```typescript src/acp.ts theme={null}
await agent.loadSession({
  sessionId: "session-abc123",
  mcpServers: [
    // MCP servers to connect
  ]
});

// Agent streams the entire conversation history via session/update notifications
// Client receives each message and tool call in order
```

<Warning>
  Loading sessions requires the agent to advertise `loadSession: true` in its capabilities.
</Warning>

### How Loading Works

1. **Client sends** `session/load` request with existing session ID
2. **Agent restores** session state from storage
3. **Agent streams** conversation history via `session/update` notifications
4. **Client rebuilds** UI state from the streamed messages
5. **Agent responds** when streaming is complete
6. **Session ready** for new prompts

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Agent
    participant Storage
    
    Client->>Agent: session/load
    Agent->>Storage: Load session data
    Storage-->>Agent: Session history
    
    loop For each message
        Agent->>Client: session/update (notification)
    end
    
    Agent-->>Client: LoadSessionResponse
    Note over Client,Agent: Session ready for prompts
```

## Resuming Sessions (Unstable)

Resume a session without replaying history:

```typescript src/acp.ts theme={null}
await agent.unstable_resumeSession({
  sessionId: "session-abc123",
  mcpServers: []
});

// Agent restores context but doesn't stream history
// Useful when client already has the history
```

<Info>
  This is an unstable feature (`unstable_resumeSession`) and may change in future versions.
</Info>

## Forking Sessions (Unstable)

Create a new session based on an existing one:

```typescript src/acp.ts theme={null}
const fork = await agent.unstable_forkSession({
  sessionId: "session-abc123",
  mcpServers: []
});

console.log(fork.sessionId); // "session-xyz789" (new ID)

// Fork has same history as original but is now independent
// Changes to fork don't affect original session
```

### Use Cases for Forking

* **Generate Summaries** - Fork to create a summary without affecting main conversation
* **Try Alternatives** - Fork to explore different approaches in parallel
* **Experimentation** - Test agent behavior without modifying original session

## Listing Sessions (Unstable)

Query available sessions:

```typescript src/acp.ts theme={null}
const response = await agent.unstable_listSessions({
  cwd: "/path/to/project", // Optional: filter by directory
  cursor: null // Optional: for pagination
});

for (const session of response.sessions) {
  console.log(session.sessionId);
  console.log(session.title);
  console.log(session.lastUpdateTime);
  console.log(session.cwd);
}

// Handle pagination
if (response.cursor) {
  const nextPage = await agent.unstable_listSessions({
    cursor: response.cursor
  });
}
```

## Session State Management

### Session Modes

Agents can support different operational modes that affect behavior:

```typescript src/acp.ts theme={null}
// Set the mode for a session
await agent.setSessionMode({
  sessionId: "session-abc123",
  mode: "code" // or "ask", "architect", etc.
});
```

Modes typically affect:

* **System prompts** - Different instructions for the LLM
* **Tool availability** - Which tools are accessible
* **Permission behavior** - Automatic vs. manual approval

<Note>
  Available modes are returned in `NewSessionResponse.availableModes` and `LoadSessionResponse.availableModes`.
</Note>

### Session Configuration

Set configuration options for a session:

```typescript src/acp.ts theme={null}
const response = await agent.setSessionConfigOption({
  sessionId: "session-abc123",
  optionId: "temperature",
  valueId: "high"
});

// Response contains all current configuration
console.log(response.configOptions);
```

### Session Model (Unstable)

Select which LLM to use for a session:

```typescript src/acp.ts theme={null}
await agent.unstable_setSessionModel({
  sessionId: "session-abc123",
  modelId: "claude-opus-4"
});
```

## Processing Prompts

Once a session is created, send prompts to the agent:

```typescript src/acp.ts theme={null}
const response = await agent.prompt({
  sessionId: "session-abc123",
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "Help me fix the bug in utils.ts"
      }
    }
  ]
});

console.log(response.stopReason); // "endTurn", "cancelled", etc.
```

### Prompt Lifecycle

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Agent
    participant LLM
    
    Client->>Agent: session/prompt
    Agent->>LLM: Generate response
    
    loop Streaming
        Agent->>Client: session/update (text chunk)
    end
    
    LLM-->>Agent: Tool call needed
    Agent->>Client: session/update (tool call)
    Agent->>Client: session/request_permission
    Client-->>Agent: Permission granted
    Agent->>Client: session/update (tool result)
    
    Agent-->>Client: PromptResponse
```

### Receiving Updates

Clients receive real-time updates via notifications:

```typescript theme={null}
class MyClient implements Client {
  async sessionUpdate(params: SessionNotification) {
    console.log("Session ID:", params.sessionId);
    
    if (params.content) {
      // Message chunk
      console.log("Content:", params.content);
    }
    
    if (params.toolCallUpdate) {
      // Tool call progress
      console.log("Tool call:", params.toolCallUpdate);
    }
    
    if (params.currentModeUpdate) {
      // Mode changed
      console.log("New mode:", params.currentModeUpdate);
    }
  }
}
```

## Cancelling Operations

Cancel an ongoing prompt:

```typescript src/acp.ts theme={null}
await agent.cancel({
  sessionId: "session-abc123"
});

// Agent should:
// 1. Stop all LLM requests
// 2. Abort tool call invocations  
// 3. Send any pending updates
// 4. Respond with stopReason: "cancelled"
```

<Warning>
  The agent may send additional `session/update` notifications before responding with the cancelled status.
</Warning>

## Session Persistence

Agents are responsible for persisting session state:

```typescript theme={null}
class MyAgent implements Agent {
  private sessions = new Map<string, SessionState>();
  
  async newSession(params) {
    const sessionId = crypto.randomUUID();
    const state = {
      id: sessionId,
      cwd: params.cwd,
      messages: [],
      mode: "code"
    };
    
    this.sessions.set(sessionId, state);
    await this.saveToDatabase(state);
    
    return { sessionId, availableModes: [...] };
  }
  
  async loadSession(params) {
    const state = await this.loadFromDatabase(params.sessionId);
    this.sessions.set(params.sessionId, state);
    
    // Stream history to client
    for (const message of state.messages) {
      await this.connection.sessionUpdate({
        sessionId: params.sessionId,
        content: message.content
      });
    }
    
    return { availableModes: [...] };
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Validate Session IDs">
    Always validate that session IDs exist and are accessible:

    ```typescript theme={null}
    async prompt(params: PromptRequest) {
      if (!this.sessions.has(params.sessionId)) {
        throw RequestError.invalidParams(
          { sessionId: params.sessionId },
          "Session not found"
        );
      }
      // Process prompt
    }
    ```
  </Accordion>

  <Accordion title="Include Session ID in All Requests">
    Every session-related operation requires the session ID:

    ```typescript theme={null}
    // ✅ Correct
    await agent.prompt({ sessionId, messages: [...] });
    await connection.sessionUpdate({ sessionId, content: {...} });

    // ❌ Wrong - missing sessionId
    await agent.prompt({ messages: [...] });
    ```
  </Accordion>

  <Accordion title="Stream History Efficiently">
    When loading sessions, batch updates to avoid overwhelming the client:

    ```typescript theme={null}
    // Send updates in chunks
    const CHUNK_SIZE = 10;
    for (let i = 0; i < messages.length; i += CHUNK_SIZE) {
      const chunk = messages.slice(i, i + CHUNK_SIZE);
      for (const msg of chunk) {
        await connection.sessionUpdate({...});
      }
      // Small delay between chunks
      await new Promise(resolve => setTimeout(resolve, 10));
    }
    ```
  </Accordion>

  <Accordion title="Handle Session Cleanup">
    Clean up resources when sessions end:

    ```typescript theme={null}
    connection.signal.addEventListener('abort', () => {
      // Clean up all active sessions
      for (const [id, session] of this.sessions) {
        session.mcpConnections.forEach(conn => conn.close());
        this.sessions.delete(id);
      }
    });
    ```
  </Accordion>
</AccordionGroup>

## Session Information

Sessions include metadata for organization:

```typescript theme={null}
interface SessionInfo {
  sessionId: string;
  title: string | null;
  lastUpdateTime: string; // ISO 8601
  cwd: string;
}
```

## MCP Server Connections

Each session can connect to MCP servers for additional tools:

```typescript theme={null}
const session = await agent.newSession({
  cwd: "/project",
  mcpServers: [
    {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      type: "sse",
      url: "https://api.example.com/mcp"
    }
  ]
});
```

<Info>
  MCP servers are connected at session creation/load and provide tools and resources to the agent.
</Info>

## Learn More

<CardGroup cols={2}>
  <Card title="Protocol Overview" icon="book" href="/concepts/protocol-overview">
    Understanding the ACP specification
  </Card>

  <Card title="Connections" icon="link" href="/concepts/connections">
    Establishing agent-client connections
  </Card>

  <Card title="Session Setup" icon="rocket" href="https://agentclientprotocol.com/protocol/session-setup">
    Full specification for session operations
  </Card>

  <Card title="Prompt Turn" icon="message" href="https://agentclientprotocol.com/protocol/prompt-turn">
    How prompts are processed in sessions
  </Card>
</CardGroup>