# Server Client Stubs

## Overview

CleverAgents defines three protocol interfaces for server communication. In
the current release all implementations are **stubs** that raise
`NotImplementedError`. When server mode is implemented as a separate project
the concrete clients will replace these stubs.

## Client Protocols

### ServerClient

Health check and version negotiation with the server.

| Method | Return | Description |
|--------|--------|-------------|
| `health_check()` | `bool` | Check server health |
| `get_version()` | `str` | Get server version |

### RemoteExecutionClient

Remote plan execution and status tracking.

| Method | Return | Description |
|--------|--------|-------------|
| `execute_plan(plan_id)` | `dict` | Submit plan for remote execution |
| `get_plan_status(plan_id)` | `dict` | Query remote plan status |
| `cancel_plan(plan_id)` | `bool` | Cancel remote plan execution |

### AuthClient

Authentication and token management.

| Method | Return | Description |
|--------|--------|-------------|
| `authenticate(token)` | `bool` | Authenticate with server |
| `validate_token(token)` | `bool` | Validate token validity |

## Stub Implementations

- `StubServerClient` — raises `NotImplementedError` for all methods
- `StubRemoteExecutionClient` — validates arguments, then raises
  `NotImplementedError`
- `StubAuthClient` — validates arguments, then raises `NotImplementedError`

## ServerConnectionConfig

Validated Pydantic model for server connection parameters.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `server_url` | `str` | *(required)* | Server URL (must be `http://` or `https://`) |
| `namespace` | `str` | `"default"` | Namespace on the server |
| `auth_token_ref` | `str \| None` | `None` | Reference to auth token |
| `tls_verify` | `bool` | `True` | Verify TLS certificates |

## Config Keys

| Key | Type | Default | Env Variable | Description |
|-----|------|---------|-------------|-------------|
| `server.url` | string | *(not set)* | `CLEVERAGENTS_SERVER_URL` | Server URL |
| `server.token` | string | *(not set)* | `CLEVERAGENTS_SERVER_TOKEN` | Auth token |
| `server.tls-verify` | bool | `true` | `CLEVERAGENTS_SERVER_TLS_VERIFY` | TLS verification |
| `server.namespace` | string | `"default"` | `CLEVERAGENTS_SERVER_NAMESPACE` | Server namespace |

## Connection Behavior

**Current mode: stub**

When `server.url` is configured, the system reports `Server Mode: stubbed` in
`agents info` output. No actual network communication occurs. The `agents server
connect <url>` command persists the URL to configuration and prints an explicit
warning that server connection is not yet implemented.

When `server.url` is not configured, the system reports `Server Mode: disabled`.

## CLI Commands

```
agents server connect <url> [--namespace NS] [--tls-verify|--no-tls-verify]
agents server status
```