# ACP (Agent Communication Protocol) Reference

## Overview

The ACP package provides the boundary layer between the CleverAgents
application core and any external orchestrator or UI.  It defines a
request/response envelope, a set of named operations, and an event
streaming interface.

**Module:** `cleveragents.acp`  
**ACP Version:** 1.0

## Table of Contents

- [Modes of Operation](#modes-of-operation)
- [Local Facade](#local-facade)
- [Operation Routing Table](#operation-routing-table)
- [Server Transport Stub](#server-transport-stub)
- [Event Queue](#event-queue)
- [Version Negotiation](#version-negotiation)
- [Models](#models)
- [Error Hierarchy](#error-hierarchy)

---

## Modes of Operation

| Mode   | Class              | Behaviour                                       |
|--------|--------------------|--------------------------------------------------|
| Local  | `AcpLocalFacade`   | Routes operations to in-process service calls    |
| Server | `AcpHttpTransport` | Stub — raises `AcpNotAvailableError` on all ops  |

In local mode the facade translates each ACP operation into a direct
Python method call.  No serialization, no network, no authentication
overhead.

---

## Local Facade

```python
from cleveragents.acp import AcpLocalFacade, AcpRequest

facade = AcpLocalFacade()
response = facade.dispatch(AcpRequest(operation="session.create"))
assert response.status == "ok"
```

### Constructor

| Parameter  | Type                       | Default | Description                   |
|-----------|----------------------------|---------|-------------------------------|
| `services` | `dict[str, Any] \| None` | `None`  | Named services for routing    |

### Methods

| Method              | Returns           | Description                          |
|---------------------|-------------------|--------------------------------------|
| `dispatch(request)` | `AcpResponse`     | Route request to handler             |
| `register_service`  | `None`            | Register a named service             |
| `list_operations`   | `list[str]`       | All supported operation names        |

---

## Operation Routing Table

| Operation              | Response Keys                           |
|------------------------|-----------------------------------------|
| `session.create`       | `session_id`, `status`                  |
| `session.close`        | `status`                                |
| `plan.create`          | `plan_id`, `status`                     |
| `plan.execute`         | `plan_id`, `status`                     |
| `plan.status`          | `plan_id`, `phase`                      |
| `plan.diff`            | `plan_id`, `changes`                    |
| `plan.apply`           | `plan_id`, `status`                     |
| `registry.list_tools`  | `tools`                                 |
| `registry.list_resources` | `resources`                          |
| `context.get`          | `context`                               |
| `event.subscribe`      | `subscription_id`, `status`             |

Unknown operations raise `AcpOperationNotFoundError`.

---

## Server Transport Stub

All methods on `AcpHttpTransport` raise `AcpNotAvailableError`:

| Method          | Description                              |
|-----------------|------------------------------------------|
| `send(request)` | Would send request over HTTP             |
| `connect(url)`  | Would open HTTP connection               |
| `disconnect()`  | Would close connection                   |
| `is_connected()`| Returns `False` (does not raise)         |

---

## Event Queue

`AcpEventQueue` provides an in-memory event queue for local mode:

| Method                | Mode   | Description                        |
|-----------------------|--------|------------------------------------|
| `publish(event)`      | Local  | Append event and notify callbacks  |
| `subscribe_local(cb)` | Local  | Register callback, return sub ID   |
| `unsubscribe(id)`     | Local  | Remove subscription                |
| `get_events(limit)`   | Local  | Return recent events               |
| `subscribe_remote(ep)`| Server | Raises `AcpNotAvailableError`      |

---

## Version Negotiation

`AcpVersionNegotiator` validates protocol version compatibility:

```python
from cleveragents.acp import AcpVersionNegotiator

negotiator = AcpVersionNegotiator()
version = negotiator.negotiate("1.0")  # returns "1.0"
negotiator.negotiate("2.0")            # raises AcpVersionMismatchError
```

Supported versions: `["1.0"]`

---

## Models

### AcpRequest

| Field         | Type                       | Default           |
|---------------|----------------------------|-------------------|
| `acp_version` | `str`                      | `"1.0"`           |
| `request_id`  | `str`                      | Auto-generated ULID |
| `operation`   | `str`                      | *required*        |
| `params`      | `dict[str, Any]`           | `{}`              |
| `auth`        | `dict[str, Any] \| None`  | `None`            |

### AcpResponse

| Field         | Type                         | Default           |
|---------------|------------------------------|-------------------|
| `acp_version` | `str`                        | `"1.0"`           |
| `request_id`  | `str`                        | *required*        |
| `status`      | `str` (`"ok"` or `"error"`)  | *required*        |
| `data`        | `dict[str, Any]`             | `{}`              |
| `error`       | `AcpErrorDetail \| None`    | `None`            |
| `timing_ms`   | `float \| None`             | `None`            |

### AcpErrorDetail

| Field     | Type              | Default |
|-----------|-------------------|---------|
| `code`    | `str`             | *required* |
| `message` | `str`             | *required* |
| `details` | `dict[str, Any]`  | `{}`    |

### AcpEvent

| Field        | Type                      | Default                |
|--------------|---------------------------|------------------------|
| `event_id`   | `str`                     | Auto-generated ULID    |
| `event_type` | `str`                     | *required*             |
| `plan_id`    | `str \| None`            | `None`                 |
| `data`       | `dict[str, Any]`          | `{}`                   |
| `timestamp`  | `str`                     | Auto-generated ISO UTC |

---

## Error Hierarchy

```
CleverAgentsError
  └── AcpError
        ├── AcpNotAvailableError
        ├── AcpVersionMismatchError
        └── AcpOperationNotFoundError
```

| Exception                   | When Raised                               |
|-----------------------------|-------------------------------------------|
| `AcpNotAvailableError`      | Server-mode operation in local mode       |
| `AcpVersionMismatchError`   | Unsupported ACP version requested         |
| `AcpOperationNotFoundError` | Unknown operation dispatched               |