AnswerUpDevelopers
Skip directly to article
DocsDeveloper ManualManual navigation ↓

Developer Manual

Provider adapters

Implement the host-owned mutation boundary without claiming effect truth.

Current package set: Core rc.1, Runtime preview.5 and Actions preview.8. Try HTTP reference preview.4 or Retell adapter preview.3 with equipment example preview.4.

Version history and scope

Retell preview.1 declarations describe the older Runtime preview.1 / Actions preview.2 line. Retell preview.2 uses a mock facade; HTTP preview.1 simulates bookkeeping. The older private HTTP source uses Runtime preview.3 / Actions preview.4. These are separate from the current runnable examples.

Examples use local test systems. They do not validate live providers, arbitrary crashes or distributed durability. Approved participants can use protected downloads.

The provider adapter is a host-owned implementation of the mutation boundary. It attempts an action against an external system; it does not establish effect truth.

Contract shape

The current contract describes a bounded mutation seam such as mutateConditional(request) and a result category such as ACKNOWLEDGED, REJECTED, PRECONDITION_FAILED, or UNCERTAIN. Use the exact exported declarations for the package version you consume. Provider-specific statuses, credentials, HTTP clients, idempotency settings, and correlation references remain behind the host boundary.

The adapter must:

  • receive a Core-bound operation/effect/execution/attempt identity;
  • use credentials only inside the host-controlled provider call;
  • preserve bounded provider outcome and stable references;
  • distinguish a request acknowledgment from authoritative effect truth;
  • apply timeouts and bounded error translation;
  • avoid a second mutation after an unresolved result.

Independent verification

The verifier must be registered separately from the provider adapter. It reads the authoritative system using the exact effect identity and applicable finality policy. A provider callback, local mutation flag, cache, or acknowledgment cannot substitute for that read.

What is not currently available

HTTP reference preview.4 is a runnable example, not a general framework adapter. Retell adapter preview.3 and equipment example preview.4 use the current package set. MCP, OpenAI/tool, Telnyx Core, Twilio Core and public web-chat adapters remain planned. Retell preview.1 declarations and preview.2 mock example are historical; local examples do not validate live providers.