Skip to content
OWP

8. The Capability Provider Contract

Capability Providers expose Capabilities to the runtime. The Provider contract defines the abstract interface a Provider MUST present, the lifecycle a Provider MUST honour, and the trust boundary at which the Provider operates.

The lifecycle, trust, and cost surfaces specified in this section apply to both invocable Capability Providers (Model, Tool, Knowledge, and Human per §3.5.3) and Signal Sources (§3.3.4). Sections specific to invocation semantics — §8.2 Invocation Semantics and §8.4 Asynchronous and Long-Running Capabilities — apply only to invocable Capability Providers; Signal Sources have emission semantics governed by §3.3 and §6.1. Implementations are encouraged to architect the two surfaces as separate subsystems sharing this Provider trust contract.

8.1 Provider Lifecycle

A Provider’s lifecycle has three phases:

  • Registration. A Provider registers with the runtime, presenting its identity, the Capabilities it offers, the schemas of those Capabilities, and any Cost-related metadata (pricing, currency, units). The runtime MUST verify the Provider’s identity per §8.5 and MUST persist the registration.
  • Operation. During operation, the Provider receives invocation requests from the runtime and returns responses. The Provider MAY also emit Signals if it is acting as a Signal Source.
  • Deregistration. A Provider MAY deregister, at which point the runtime MUST cease routing invocations to it. Open invocations MAY be permitted to complete or MAY be cancelled, depending on the runtime’s policy and any Compliance Profile constraints.

8.2 Invocation Semantics

A Capability invocation is a request-response interaction in the abstract. The protocol distinguishes three concrete semantics:

  • Synchronous. The Provider returns a response within a bounded time window. The Worker is blocked on the response.
  • Asynchronous. The Provider acknowledges the invocation and produces a response at some later time. The Worker is not blocked; it continues other work and is delivered the response (typically as an Internal Signal) when it arrives.
  • Streaming. The Provider returns a sequence of partial responses culminating in a final response. The Worker receives the partial responses as Internal Signals during the stream.

A Capability’s invocation semantics MUST be declared in its kind URI’s schema. A runtime MUST support all three semantics; a Provider MAY support a subset (declared in its registration).

8.3 Cost Reporting

Every Capability invocation MUST result in a Cost Record (§10). The Provider MUST report cost as part of the invocation response, in the Cost units declared at registration. The runtime MUST embed the Cost Record in the CapabilityInvoked (or equivalent) event of the Audit Envelope.

Where cost cannot be precisely reported at the moment of response (e.g. amortised infrastructure costs), the Provider MUST report a defensible estimate, marked as such, and SHOULD provide a corrected record at a later time. The corrected record MUST refer to the Envelope event it corrects.

8.4 Asynchronous and Long-Running Capabilities

For asynchronous and human Capabilities, an invocation may remain open for periods that exceed runtime restarts. The runtime MUST persist outstanding invocations such that responses arriving after a restart are correctly correlated to the originating invocation event in the Audit Envelope.

The Provider MUST support correlation via an opaque invocation ID issued by the runtime at the moment of invocation. The Provider MUST attach this ID to all responses, partial and final.

8.5 Trust and Authentication

The runtime and Providers MUST mutually authenticate. The protocol REQUIRES authenticated, integrity-protected, confidential transport for all invocation traffic. The mechanism is a wire-binding concern (§17); but at the abstract level:

  • The runtime MUST hold a verified identity for every registered Provider.
  • The Provider MUST hold a verified identity for the runtime to which it is connected.
  • Either party MAY refuse a request whose authentication is invalid.

A Provider that misrepresents Cost, returns invalid responses, or otherwise violates the contract MUST be flagged in the Audit Envelope and MAY be deregistered by the runtime. Compliance Profiles MAY require deregistration of non-conforming Providers.