# AgentSession

**Kind:** Class

**Source:** [`atloria-monorepo/libs/agent-core/src/session/agent-session.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/libs/agent-core/src/session/agent-session.ts#L80)

Interactive agent session.

Usage:
```typescript
const session = new AgentSession(runtime, agentConfig, { maxTurns: 30 });
session.on('tool_start', (e) => console.log(`Using ${e.toolName}...`));
session.on('agent_message', (e) => console.log(e.text));

const result = await session.send('Build a login page');
const result2 = await session.send('Add password validation');
```

**Extends:** `EventEmitter`

## Methods

| Method | Signature | Returns |
|---|---|---|
| `on` | `on(event: K, listener: (data: SessionEventMap[K]) => void)` | `this` |
| `off` | `off(event: K, listener: (data: SessionEventMap[K]) => void)` | `this` |
| `emit` | `emit(event: K, data: SessionEventMap[K])` | `boolean` |
| `send` | `send(message: string)` | `Promise<RunResult>` |
| `inject` | `inject(message: string)` | `void` |
| `cancel` | `cancel()` | `void` |
| `getState` | `getState()` | `SessionState` |
| `getHistory` | `getHistory()` | `AgentHistoryItem[]` |
| `getUsage` | `getUsage()` | `TokenUsage` |
| `getSendCount` | `getSendCount()` | `number` |
| `getTurnCount` | `getTurnCount()` | `number` |
| `getSnapshot` | `getSnapshot()` | `{ conversationHistory: AgentHistoryItem[]; sdkHistory: unknown[] }` |
| `loadHistory` | `loadHistory(conversationHistory: AgentHistoryItem[], sdkHistory: unknown[])` | `void` |
| `end` | `end()` | `void` |
| `setVerbose` | `setVerbose(enabled: boolean)` | `void` |
| `isVerbose` | `isVerbose()` | `boolean` |
| `isPlanMode` | `isPlanMode()` | `boolean` |
| `getActiveModel` | `getActiveModel()` | `string | undefined` |
| `approvePlan` | `approvePlan(feedback: string)` | `Promise<RunResult>` |
| `revisePlan` | `revisePlan(feedback: string)` | `Promise<RunResult>` |
| `fork` | `fork(branchName: string)` | `AgentSession<TContext>` |

## Where it refuses work

- `AgentSession` stops the work with `Error` when `this.state === 'running'` — “Session is already processing a message. Use inject() for mid-task messages.”.
- `AgentSession` stops the work with `Error` when `result.blocked`.
- `AgentSession` stops the work with `Error` when `this.state !== 'running'` — “Cannot inject: session is not running. Use send() instead.”.
- `AgentSession` stops the work with `Error` when `this.state !== 'idle'` — “Cannot load history: session is not idle.”.
- `AgentSession` stops the work with `Error` when `this.history.length > 0 || this.conversationHistory.length > 0` — “Cannot load history: session already has history.”.
- `AgentSession` stops the work with `Error` when `!this.planMode` — “Cannot approve plan: session is not in plan mode.”.

## When something fails

- `AgentSession` handles failure in 6 places: it lets it reach the caller in 3, and discards it silently in 3. A failure discarded silently leaves no trace for whoever debugs this later.