forked from HAL9000/cleveragents-core
freemo
c781848cb6
Add protocol stubs for remote server communication infrastructure: - ServerClient: Health check and version negotiation protocol - RemoteExecutionClient: Remote plan execution and status protocol - AuthClient: Authentication and token management protocol - StubServerClient/StubRemoteExecutionClient/StubAuthClient: Stub implementations raising NotImplementedError for all methods - ServerConnectionConfig: Validated config model (server_url, namespace, auth_token_ref, tls_verify) - Config keys: core.server_url, core.server_namespace, core.server_tls_verify - CLI: agents connect <url> stub command with explicit warning - CLI: agents info shows Server Mode (disabled/stubbed) ISSUES CLOSED: #201
84 lines
2.8 KiB
Markdown
84 lines
2.8 KiB
Markdown
# 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
|
|
```
|