AlexandrAI AGENTS.md
agents-md

Personal Work Agent Sync Transport Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent outbound sync transport, Socket.IO auth, HTTP polling, pending items, onboarding sync, and tests.

AGENTS.md

Guidance for coding agents working on the Personal Work Agent sync transport boundary.

Project Overview

The sync layer connects the local agent to the paired service through outbound Socket.IO and HTTP polling. It pulls review commands, pending items, onboarding items, session messages, and model or installation updates; it acknowledges work and posts results. HMAC signing and installation identifiers bind the local runtime to a paired account.

This boundary should remain outbound-initiated. Do not add behavior that requires exposing the local agent publicly.

Project Map

  • src/workagent/sync/client.py defines ReviewSyncClient and signed HTTP request behavior.
  • src/workagent/sync/factory.py builds clients from environment, stored installation settings, and supported placeholders.
  • src/workagent/sync/poller.py handles cursor-based command polling.
  • src/workagent/sync/runtime.py runs review sync cycles.
  • src/workagent/sync/agent_runtime.py runs pending and onboarding sync cycles.
  • src/workagent/sync/agent_socket_transport.py implements Socket.IO transport auth and event handling.
  • src/workagent/sync/models.py defines review, pending, onboarding, draft, account status, and installation payload models.
  • src/workagent/services/agent_pending_sync.py, agent_onboarding_sync.py, agent_session_outbox.py, and sync_metadata.py consume sync payloads.

Setup Commands

bashuv run pytest tests/test_agent_sync_client.py tests/test_sync_poller.py tests/test_review_sync_runtime.py -q
uv run pytest tests/test_agent_socket_transport.py tests/test_agent_pending_sync.py tests/test_agent_onboarding_sync.py -q
uv run pytest tests/test_socket_transport_dependency_contract.py -q
make lint

Change Rules For Agents

  • Preserve outbound-only transport. Do not introduce required public listeners.
  • Keep signing centralized and testable. Any signed request change must update HMAC tests and sync client tests.
  • Keep cursor handling idempotent: acknowledgements and result posts should tolerate retries.
  • Validate payload models in src/workagent/sync/models.py before routing to services.
  • Keep environment placeholder detection conservative so sample values do not create live clients.
  • Do not log pairing secrets, signatures, tokens, raw payload bodies with credentials, or private endpoints.
  • Maintain separate pending, onboarding, review command, and session message paths.

Verification

bashuv run pytest tests/test_agent_sync_client.py tests/test_review_client_factory.py tests/test_sync_poller.py -q
uv run pytest tests/test_agent_pending_runtime.py tests/test_agent_pending_sync_relay.py tests/test_agent_socket_transport.py -q
make lint

For schema changes, add or update model validation tests and service-level consumers.

Security Notes

Transport code handles installation secrets, signatures, command payloads, and local action results. Keep secrets out of fixtures and redact them in logs. Use placeholders for public documentation.

PR Checklist

  • Sync client signing and timestamp behavior remain verified.
  • Poller cursor behavior is idempotent.
  • Socket transport handles auth and reconnect cases.
  • Pending, onboarding, and review result paths remain separate.