> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Channel

> AI agent interaction and streaming

## Overview

The `agent` channel carries AI agent prompts, streaming responses, and tool interactions. The agent processes natural language prompts, executes tools in the workspace, and streams results back to the client.

## Client to Server Messages

### `prompt`

Start a new agent task with a natural language prompt.

```json theme={null}
{
  "channel": "agent",
  "type": "prompt",
  "prompt": "Create a REST API with Express that has CRUD endpoints for users",
  "taskId": "task-abc-123"
}
```

| Field    | Type   | Required | Description                                   |
| -------- | ------ | -------- | --------------------------------------------- |
| `prompt` | string | Yes      | Natural language instruction for the agent    |
| `taskId` | string | No       | Client-generated task identifier for tracking |

### `settings`

Configure agent behavior for the current session.

```json theme={null}
{
  "channel": "agent",
  "type": "settings",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5-20250929"
}
```

| Field      | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| `provider` | string | No       | LLM provider name |
| `model`    | string | No       | Model identifier  |

### `abort`

Cancel a running agent task.

```json theme={null}
{
  "channel": "agent",
  "type": "abort",
  "taskId": "task-abc-123"
}
```

| Field    | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `taskId` | string | Yes      | Task to cancel |

### `tool_response`

Respond to a tool call that requires user input.

```json theme={null}
{
  "channel": "agent",
  "type": "tool_response",
  "toolCallId": "tc-456",
  "result": "Yes, use PostgreSQL for the database"
}
```

| Field        | Type   | Required | Description                       |
| ------------ | ------ | -------- | --------------------------------- |
| `toolCallId` | string | Yes      | ID of the tool call to respond to |
| `result`     | string | Yes      | User's response                   |

### `approve`

Approve a permission request from the agent (e.g., before running a destructive command).

```json theme={null}
{
  "channel": "agent",
  "type": "approve",
  "requestId": "perm-789"
}
```

| Field       | Type   | Required | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `requestId` | string | Yes      | Permission request to approve |

### `reject`

Reject a permission request from the agent.

```json theme={null}
{
  "channel": "agent",
  "type": "reject",
  "requestId": "perm-789"
}
```

| Field       | Type   | Required | Description                  |
| ----------- | ------ | -------- | ---------------------------- |
| `requestId` | string | Yes      | Permission request to reject |

## Server to Client Events

The agent streams events as it processes a task. Events arrive in order and represent the agent's reasoning, tool use, and final output.

### `text`

Streamed text output from the agent.

```json theme={null}
{
  "channel": "agent",
  "type": "text",
  "content": "I'll create a REST API with Express..."
}
```

| Field     | Type   | Description              |
| --------- | ------ | ------------------------ |
| `content` | string | Incremental text content |

Text events are streamed token-by-token. Concatenate all `text` events to build the full response.

### `thinking`

Agent reasoning content (available for models that support extended thinking).

```json theme={null}
{
  "channel": "agent",
  "type": "thinking",
  "content": "The user wants CRUD endpoints. I should create routes for GET, POST, PUT, DELETE..."
}
```

| Field     | Type   | Description             |
| --------- | ------ | ----------------------- |
| `content` | string | Internal reasoning text |

### `tool_invocation`

The agent is calling a tool.

```json theme={null}
{
  "channel": "agent",
  "type": "tool_invocation",
  "toolCallId": "tc-456",
  "toolName": "write_file",
  "args": {
    "path": "/src/routes/users.ts",
    "content": "import { Router } from 'express';\n..."
  }
}
```

| Field        | Type   | Description                          |
| ------------ | ------ | ------------------------------------ |
| `toolCallId` | string | Unique identifier for this tool call |
| `toolName`   | string | Name of the tool being invoked       |
| `args`       | object | Arguments passed to the tool         |

### `tool_result`

A tool call has completed.

```json theme={null}
{
  "channel": "agent",
  "type": "tool_result",
  "toolCallId": "tc-456",
  "result": "File written: /src/routes/users.ts"
}
```

| Field        | Type             | Description                   |
| ------------ | ---------------- | ----------------------------- |
| `toolCallId` | string           | ID of the completed tool call |
| `result`     | string or object | Tool execution result         |

### `question`

The agent is asking the user for input.

```json theme={null}
{
  "channel": "agent",
  "type": "question",
  "questions": [
    "Which database would you like to use: PostgreSQL, MySQL, or SQLite?"
  ]
}
```

| Field       | Type             | Description                        |
| ----------- | ---------------- | ---------------------------------- |
| `questions` | array of strings | Questions the agent needs answered |

Respond with a `tool_response` message to continue the agent's task.

### `result`

The agent turn has produced a result.

```json theme={null}
{
  "channel": "agent",
  "type": "result",
  "summary": "Created Express REST API with CRUD endpoints for users at /src/routes/users.ts"
}
```

| Field     | Type   | Description                      |
| --------- | ------ | -------------------------------- |
| `summary` | string | Summary of what was accomplished |

### `error`

The agent task failed.

```json theme={null}
{
  "channel": "agent",
  "type": "error",
  "message": "Failed to install dependencies: npm ERR! 404 Not Found"
}
```

| Field     | Type   | Description       |
| --------- | ------ | ----------------- |
| `message` | string | Error description |

### `done`

Stream is complete. No more events will be sent for this task.

```json theme={null}
{
  "channel": "agent",
  "type": "done"
}
```

## Conversation History

Agent conversation history is persisted to the database. On WebSocket reconnect, previous messages are replayed so the client can restore the conversation UI.

History supports undo and truncation via soft-delete, allowing users to roll back the conversation to an earlier point and re-prompt from there.