Add structured task/step payload support for BYOA adapters

[jbarnes850]

Summary

Adds opt-in structured task and step payload support for BYOA adapters, enabling integration with test harnesses and simulation environments without requiring prompt parsing.

Problem

Arc CRM benchmark integration (arc-crm-benchmark#45) requires access to structured execution context to reconstruct test harness turn data. Current implementation only passes natural language prompts to adapters, forcing brittle prompt parsing.

Solution

Added capability flag system (supports_structured_payloads) that gates structured metadata enrichment:

• Python adapters opt-in automatically
• LLM adapters (OpenAI, LiteLLM) remain opted-out by default
• Structured payloads passed via LangGraph config to avoid race conditions in concurrent execution

Changes

Core Implementation

• registry.py: Added supports_structured_payloads flag to AgentAdapter base class
• python.py: Enabled flag for PythonAdapter
• langchain_bridge.py: Gate metadata enrichment with capability check
• student.py: Pass step_payload via LangGraph config per invocation

Metadata Additions

# Planning phase
metadata = {
    "mode": "planning",
    "task_payload": str  # Original task
}

# Execution phase  
metadata = {
    "task_payload": str,
    "step_payload": {
        "step_id": int,
        "description": str,
        "depends_on": List[int]
    }
}

Testing

• Added 9 comprehensive tests covering planning, execution, concurrent steps, and backward compatibility
• All existing tests pass (18 student tests, 4 adapter tests)

Documentation

• Complete developer guide with use cases, examples, best practices
• Clear opt-in requirement and security considerations

Security & Privacy

• LLM adapters never receive structured payloads (prevents PII leaks to external providers)
• Opt-in only: adapters must explicitly set flag
• No impact on existing LLM provider costs or privacy

Performance

• Payload size: 500 bytes - 2KB per step (lightweight)
• No race conditions in concurrent execution (per-step config isolation)
• Zero impact on LLM-based adapters

Backward Compatibility

Fully backward compatible:

• Existing adapters work unchanged
• LiteLLM/OpenAI adapters unaffected
• Python adapters receive payloads but can ignore them
• No API changes to AgentAdapter.ainvoke()

Testing

All tests passing:

• test_structured_payloads.py: 9/9 passed
• test_student.py: 18/19 passed (1 skipped - API key)
• test_litellm_adapter.py: 4/4 passed

Resolves

Arc-Computer/CL-Bench#45

[Copilot]

Pull Request Overview

This PR adds opt-in structured task and step payload passing to BYOA adapters, enabling integration with test harnesses and deterministic execution environments while protecting LLM-based adapters from data leakage.

Key Changes:

• Introduces supports_structured_payloads flag on adapters to control metadata enrichment
• Passes task_payload and step_payload through metadata to opt-in adapters during planning and execution phases
• Uses LangGraph config metadata to avoid race conditions in concurrent step execution

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
atlas/connectors/registry.py	Adds supports_structured_payloads class attribute (default False) to AgentAdapter base class
atlas/connectors/python.py	Sets supports_structured_payloads = True for Python adapters to enable BYOA integration
atlas/connectors/http.py	Sets supports_structured_payloads = True for HTTP adapters (remote BYOA services)
atlas/connectors/langchain_bridge.py	Enriches metadata with task/step payloads from ExecutionContext when adapter opts-in
atlas/personas/student.py	Passes task payload during planning and step payload during execution via config metadata
tests/unit/test_structured_payloads.py	Comprehensive test coverage for payload passing, concurrency safety, and backward compatibility
examples/byoa_structured_adapter.py	Example adapters demonstrating structured payload usage patterns
docs/sdk/structured_adapter_payloads.md	Complete documentation with use cases, best practices, and migration guide

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.