feat(deliverables): pure-agent-dev reference implementation

[fig-ai-agent]

Implements the Code Guide: pure-agent-dev from #63 — a provider-agnostic agent skeleton on FastAPI, with BytePlus ECS as the first adapter.

42 files, +1401 lines. Placed in deliverables/ per repo convention; the main application tree is untouched.

The rule this exists to enforce

The Agent must never depend on the BytePlus SDK.

That is the whole point of the guide, and a comment cannot hold it. tests/test_architecture.py parses the real import graph and fails if any layer reaches across the interface:

api -> services -> agents -> providers.base -> adapter -> cloud SDK

Four guards, all failing on the real thing rather than a style rule:

• agents/, services/, schemas/ may not import any concrete adapter
• agents/ may not mention a cloud SDK name at all
• only api/deps.py may name a concrete adapter
• the only provider import allowed above the interface is providers.base

Adding an AWS adapter, then, is one new file plus one line of wiring — nothing above providers/ moves.

Layers

Layer	Role
providers/base.py	ComputeProvider ABC — the contract every cloud implements
providers/mock.py	in-memory provider — CI needs no credentials
providers/byteplus/	real adapter (shape complete, SDK calls TODO(byteplus))
agents/planner.py	intent → AgentTask, provider-free by construction
agents/executor.py	AgentTask → provider, only through the interface
api/deps.py	the single place a provider is selected and injected

Provider choice is configuration, not code: COMPUTE_PROVIDER=mock|byteplus.

Two contracts, checked against each other

The guide left the task shape implicit. It is now written twice on purpose:

• schemas/agent-task.schema.json — the external contract (JSON Schema draft 2020-12)
• pure_agent/schemas/task.py — the runtime Pydantic model

tests/test_schema_contract.py asserts they agree — including that the action enum is identical in both. Drift between those two is the failure that silently breaks every consumer, so it is a test, not a review note.

Verification

Check	Result
pytest	47 passed
pytest -O	47 passed — proves no assert is doing control-flow work
ruff check .	clean
JSON Schema	valid draft 2020-12, matches the Pydantic model
App boots	GET /health → 200 on the mock provider, zero credentials

The -O run is not ceremony: the first version of executor.py guarded instance_id with a bare assert, which python -O strips — turning the guard into a silent None passed to the provider. It is now a raise.

Scope and honesty

• The BytePlus adapter's SDK calls are stubs (TODO(byteplus)). Signatures, return types and the interface are final; filling them in touches no other file. It cannot be validated against a real account from here.
• No live cloud call has been made. Every test runs on MockComputeProvider.
• This PR contains no .github/workflows/ changes. The bundled deliverables/pure-agent-dev/.github/workflows/ci.yml is a new file path, so it does not trip the App's workflows restriction — but it will not run until it is moved to the repo's own workflows directory by a maintainer.

Closes #63.