forked from cleveragents/cleveragents-core
freemo
ae1fd648d5
Implement PlanSyncClient for synchronizing local resources with a remote CleverAgents server and submitting plans for remote execution: - Sync actions, skills, tools, projects with configurable scope flags - Conflict resolution policies (local_wins / server_wins) - Remote plan execution, apply, and status query endpoints - Server-side ID persistence in local item metadata - Sync summary output (created/updated/skipped/errors) - Dry-run mode that skips server mutations - SyncScope, SyncSummary, ExecutionResult data models - Behave scenarios (18 scenarios, 62 steps) - Robot Framework smoke tests - ASV benchmark for sync throughput baseline - Reference documentation at docs/reference/server_sync.md ISSUES CLOSED: #336
68 lines
1.9 KiB
Markdown
68 lines
1.9 KiB
Markdown
# Server Sync and Remote Execution
|
|
|
|
The `PlanSyncClient` synchronizes local resources (actions, skills, tools,
|
|
projects) with a remote CleverAgents server and supports remote plan
|
|
execution, apply, and status queries.
|
|
|
|
## Configuration
|
|
|
|
Sync uses the same server connection configured via the
|
|
[HTTP client](server_client_http.md) settings (`CLEVERAGENTS_SERVER_BASE_URL`,
|
|
`CLEVERAGENTS_SERVER_API_TOKEN`).
|
|
|
|
## Sync Scope
|
|
|
|
By default, sync transfers the minimal set of resources required for
|
|
a plan. Use scope flags to control which entity types are synchronized:
|
|
|
|
| Flag | Entity type |
|
|
|---|---|
|
|
| `--actions` | Actions |
|
|
| `--skills` | Skills |
|
|
| `--tools` | Tools |
|
|
| `--projects` | Projects |
|
|
|
|
## Conflict Resolution
|
|
|
|
When a local entity and a server entity share the same name but differ
|
|
in content, the conflict resolution policy determines the outcome:
|
|
|
|
| Policy | Behaviour |
|
|
|---|---|
|
|
| `local_wins` | Local version overwrites the server version |
|
|
| `server_wins` | Server version is kept; local changes are discarded |
|
|
|
|
If no policy is set and a conflict is detected, the client raises a
|
|
`ValueError` with an explanatory message.
|
|
|
|
## Dry-Run Mode
|
|
|
|
Pass `dry_run=True` to `sync_all()` to preview what would be
|
|
synchronized without executing any mutations on the server.
|
|
|
|
## Sync Summary
|
|
|
|
After a sync operation the client returns a `SyncSummary` with counts:
|
|
|
|
| Field | Meaning |
|
|
|---|---|
|
|
| `created` | Items created on the server |
|
|
| `updated` | Items updated on the server |
|
|
| `skipped` | Items unchanged (already in sync) |
|
|
| `errors` | Items that failed to sync |
|
|
|
|
## Remote Execution
|
|
|
|
```python
|
|
from cleveragents.client.sync_client import PlanSyncClient
|
|
|
|
sync = PlanSyncClient(http_client)
|
|
result = sync.execute_plan("PLAN001")
|
|
print(result.status, result.remote_plan_id)
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Sync and execution errors propagate from the underlying HTTP client.
|
|
See [Server HTTP Client — Connection Errors](server_client_http.md#connection-errors).
|