Skip to main content

Cloud backend integration plan

Goal​

Add a cloud task backend to Agentplane without embedding connector-specific logic in the public CLI.

The public CLI should expose local and cloud backend choices. The cloud service decides which connector is attached to a cloud project.

Boundary​

Public Agentplane owns:

  • cloud backend id and config loading;
  • local projection cache;
  • cloud API client;
  • backend connect cloud;
  • explicit backend sync cloud --direction pull|push;
  • backend inspect cloud;
  • stale projection guard before task mutations;
  • user docs and generated CLI reference.

The cloud service owns:

  • connector authorization;
  • connector webhooks;
  • connector field mapping;
  • connector API calls;
  • sync queue;
  • conflict records;
  • service deployment.

Atomic tasks​

C001: Add cloud backend config contract​

Scope:

  • add cloud backend id to init/config typing;
  • define backend JSON settings;
  • document non-secret backend JSON boundaries;
  • add schema/examples for cloud backend config.

Verification:

  • config schema check;
  • init parser tests for accepted backend ids;
  • docs routing check.

Status: implemented in the first Agentplane layer. agentplane init --backend cloud now writes .agentplane/backends/cloud/backend.json and cloud .env.example keys.

C002: Implement CloudBackend as a remote-cache backend​

Scope:

  • add CloudBackend under packages/agentplane/src/backends/task-backend/;
  • use LocalBackend as the projection cache;
  • expose remote-cache capabilities;
  • keep ordinary task reads on the projection.

Verification:

  • backend capability unit tests;
  • projection read/write tests with mocked cloud client.

Status: implemented in the first Agentplane layer. CloudBackend wraps LocalBackend as a cache and reports a remote canonical source.

C003: Add cloud API client​

Scope:

  • implement connector-neutral HTTP client for inspect, pull, push, state, and conflicts;
  • map service errors into teaching CLI diagnostics;
  • keep authentication outside committed config.

Verification:

  • mocked HTTP tests;
  • error-code mapping tests.

Status: implemented for the public CLI contract. The current API surface posts to /v1/projects/{project_id}/sync/{pull|push} with provider, direction, conflict, and local tasks for push sync. Pull also reads /v1/projects/{project_id}/sync/state so open service conflicts can stop --conflict=fail before projection writes.

Bidirectional pull support accepts both response.tasks and response.data.tasks, preserves last_checked_at from either envelope level, and surfaces service remediation fields (why, fix, safe_command, when_to_stop) when a service-side direction or conflict policy rejects the request.

Authoritative pull application is fail-closed. A prefer-remote pull, initial identity adoption, or interrupted adoption resume requires a task array plus projection_complete: true at the response or data level. Without that explicit full-snapshot marker, the CLI does not interpret missing task ids as deletions and does not bind the cache to the remote identity.

Push requests carry a projection object with request_id, projection_sha256, task_count, project_id, and provider. The service must return a matching data.projection_ack with status: "persisted" or status: "unchanged" and the same fields. Batched pushes must also echo the exact batch_id, while data.batch must report the same id and finalized: true. An HTTP 2xx response, timestamp, generic no-op marker, or uncorrelated batch marker does not clear local dirty state.

C004: Add backend connect command​

Scope:

  • add agentplane backend connect cloud;
  • support provider URL override;
  • open/browser-print onboarding URL;
  • write returned workspace/project connection metadata.

Verification:

  • command parser tests;
  • non-interactive output tests;
  • config write tests.

Status: implemented as non-interactive handoff from the cloud service: agentplane backend connect cloud --endpoint ... --project-id ... --provider ... --token .... Backend JSON stores only non-secret metadata; the CLI token is written to ignored project .env as AGENTPLANE_CLOUD_TOKEN. Browser-based authorization remains owned by the cloud service.

C005: Add stale projection guard​

Scope:

  • warn on stale remote-cache projections for read commands;
  • block local task mutations when cloud projection is stale;
  • show the next safe pull command.

Verification:

  • task mutation tests for fresh/stale cloud state;
  • read-command warning tests.

Status: implemented for local task writes. Cloud sync records .agentplane/backends/cloud/state.json with last_checked_at; backend inspect cloud --yes reports stale/fresh state. Mutation blocking lives at the cloud backend write boundary: local task writes are refused when state.json is stale, while explicit sync/inspect commands remain available. The safe command shown to operators is:

agentplane backend sync cloud --direction pull

C006: Add sync and inspect behavior​

Scope:

  • wire backend sync cloud --direction pull|push;
  • wire backend inspect cloud;
  • surface connection status, connector display name, freshness, and conflicts.

Verification:

  • backend sync CLI tests;
  • backend inspect CLI tests.

Status: implemented for the current cloud service contract. backend sync cloud uses the backend sync port; backend inspect cloud --yes shows connection and freshness metadata. Pull checks service conflict state, blocks --conflict=fail when conflicts are open, and keeps --conflict=diff read-only with a local summary instead of applying projection writes.

For bidirectional projects, pull applies only service-approved operational fields to already known local task IDs. Full task documents returned by the service are treated as projection sources for those fields only; Agentplane-owned lifecycle, planning, verification, findings, rollback, comments, events, and README content are preserved. Remote-only service items are ignored until a remote_create_policy decision is made.

Current remote-only policy:

  • diff is the default and reports remote-only items without writing local READMEs or advancing freshness.
  • ignore records the pull freshness while leaving remote-only items outside Agentplane task storage.
  • import materializes remote-only items as conservative local README tasks using the provider-neutral sync envelope for external identity and field authority.

C007: Update init UX and docs​

Scope:

  • make local and cloud the primary backend choices in onboarding;
  • route Redmine through the cloud connector service instead of direct public backend support;
  • update setup, backend docs, generated CLI reference, and navigation.

Verification:

  • init interactive tests;
  • docs IA check;
  • generated CLI reference check if command text changes.

C008: Add v0.7 runner handoff contract​

Scope:

  • add a public AgentPlaneRunnerHandoff schema/type to @agentplaneorg/core;
  • validate task/run/project/workspace IDs, safe repo_ref, expiry, execute-mode feature gating, and global kill-switch state;
  • expose a sanitizer for public/list responses;
  • document evidence and artifact upload target expectations without giving the public CLI hosted execution authority.

Verification:

  • schema fixture validation;
  • unit tests for missing IDs, unsafe refs, execute gating, kill switch, expiry, and sanitization;
  • docs routing check.

Status: prepared for the v0.7 release lane. The contract is intentionally connector-neutral and does not add hosted execution, repository mutation commands, or connector-specific public CLI logic.

Stop rules​

Stop before implementation if:

  • the cloud service API contract is not stable enough to mock;
  • a task requires connector-specific logic in the public CLI;
  • a command would need to store tokens in backend JSON;
  • stale projection behavior cannot be enforced consistently across task mutations.