Skip to content

Define ProviderAdapter interface and normalised result/event/usage types #16

Description

@Ryan-Atkinson87

Define the single interface the orchestrator uses to invoke any AI provider, plus the normalised result/event/usage types that let the engine and UI treat every provider identically. This is the architectural seam Spec §3.3 mandates: orchestration code calls only this interface, never a provider SDK directly. Provider-neutral; no Claude specifics here.

Spec §3.1 (Adapter interface), §3.3 (Build order + MVP note), §4.3 (Fresh sessions).

Acceptance criteria

  • A ProviderAdapter abstract interface (ABC or Protocol) with a single run_session(workdir, role, model, allowed_tools, prompt, context_files) -> SessionResult method, matching the Spec §3.1 signature exactly.
  • role is constrained to "orchestrator" | "implementor"; outcome to "completed" | "blocked" | "error".
  • SessionResult carries events (a stream/iterable of NormalisedEvent), usage: UsageReport, outcome, and artifacts: list[path] (declared as "files changed, derived from git, not self-report" in the docstring).
  • NormalisedEvent models the four event kinds in Spec §3.1 (reasoning / tool-call / tool-result / output) in a provider-neutral shape suitable for SSE streaming to the UI.
  • UsageReport carries tokens in/out, cost, model, and duration.
  • All types are Pydantic models (or dataclasses) with no imports from any provider SDK — verified by the module having zero anthropic/claude imports.
  • Docstrings note that each call is a fresh, stateless session (§4.3) and that multi-provider event-mapping depth is deferred (§3.3 MVP note) — this issue establishes the seam only.
  • Unit tests assert the interface cannot be instantiated directly and that a trivial fake adapter satisfies it.

Notes

This is the boundary enforced by the "provider specifics stay behind ProviderAdapter" architecture rule. Keep it Claude-free so adding Codex/Gemini later (Phase 7) is purely additive.

Depends on: #1

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions