Phase Planning — Phoenix Agentic Engine Interface
Repo Context
This is the Interface SDK (TypeScript). It defines contracts between Engine and Backend.
Current Status
- Phase 1 foundation: Complete — fixtures, typed SDK, transport, validators, tests
Next steps
- Keep contract fixtures in sync as backend evolves
- Add WebSocket transport support for real-time streaming (Phase 5+)
- Add
v2contract namespace when breaking changes are needed - Expand test coverage for edge cases
- Publish as npm package when ready for external consumption
How Interface fits into project phases
| Phase | Interface involvement |
|---|---|
| Phase 0 | Complete — contracts, SDK, tests |
| Phase 1 | Engine integrates SDK into adapter layer |
| Phase 2 | Add delta sync transport, sequence validation |
| Phase 3 | Add tool invocation contract types |
| Phase 4 | Add parallel plan / worktree contract types |
| Phase 5+ | WebSocket streaming, advanced transport |
Key deliverables this repo owns
contracts/v1/*.json— golden fixture mirrorssdk/client/PhoenixClient.ts— typed HTTP clientsdk/client/types.ts— request/response TypeScript typessdk/transport/— HTTP transport with retry/backoffsdk/validators/— Zod validation schemastests/contract/— fixture validation teststests/compatibility/— SDK compatibility tests
Working principles
- Stay protocol-only — no UI, no orchestration, no business logic
- Contract compatibility is non-negotiable
- Keep dependencies minimal
- Both Engine and Backend depend on this repo
- Test edge cases — malformed payloads, network errors, retry exhaustion