forked from cleveragents/cleveragents-core

Files

T

freemo ae1fd648d5 feat(client): add plan sync and remote execution

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

2026-03-24 20:28:19 +00:00

1.9 KiB

Raw Permalink Blame History

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 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

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.

1.9 KiB Raw Permalink Blame History