feat(providers): add shared authentication and resilience (#16)

## Summary

Adds shared authentication and resilience configuration across AgentKit
model providers. Introduces separate OpenAI Chat Completions and
Responses adapters, including configurable support for public OpenAI
Responses and private ChatGPT deployments.

## Motivation

Provider adapters previously stored raw credential strings and
implemented inconsistent authentication, retry, timeout, and
stream-recovery behavior. This change gives providers reusable
HTTP-layer authentication and resilience primitives while keeping each
provider’s authentication scheme and wire protocol explicit.

## Impact

Existing constructors continue to accept string credentials, and omitted
resilience preserves the current single-attempt behavior. The following
public API changes require migration:

- Provider config fields such as `api_key` and `auth_token` become
`authentication: Authentication`; Ollama and vLLM use
`Option<Authentication>` because authentication remains optional.
- Provider config structs gain `resilience: Option<ResilienceConfig>`.
Exhaustive struct literals must add `resilience: None` or move to
constructors and builders.
- `SessionConfig` gains `consumer_capabilities`; direct struct literals
must add the field or use `SessionConfig::new(...)`.
- `ModelTurnEvent` and `AgentEvent` gain `ResponseAttemptSuperseded`;
exhaustive matches must handle the new variant.
- Anthropic still distinguishes `x-api-key` from bearer authentication.
A bare string converted directly to `Authentication` always means bearer
authentication.

## Technical details

### Shared authentication API

`agentkit-http` now exports `Authentication`, `AuthenticationAttempt`,
and the asynchronous `AuthenticationProvider` contract. A provider
receives `None` for initial authentication and the rejected attempt
after a `401`, allowing one controlled refresh while keeping
provider-private state opaque.

Static bearer authentication remains concise:

```rust
use agentkit_http::Authentication;

let from_string: Authentication = "sk-example".into();
let explicit = Authentication::bearer("sk-example");
```

Refreshable authentication can retain rejected-attempt state and attach
a stable, non-secret binding:

```rust
use agentkit_http::{
    header, Authentication, AuthenticationAttempt, AuthenticationProvider,
    HeaderMap, HeaderValue, HttpError,
};
use async_trait::async_trait;

#[derive(Clone, Copy)]
struct RotatingTokens;

#[async_trait]
impl AuthenticationProvider for RotatingTokens {
    async fn authenticate(
        &self,
        previous: Option<&AuthenticationAttempt>,
    ) -> Result<AuthenticationAttempt, HttpError> {
        let generation = previous
            .and_then(|attempt| attempt.state::<u64>())
            .copied()
            .map_or(0, |generation| generation + 1);

        let value = match generation {
            0 => HeaderValue::from_static("Bearer initial-token"),
            _ => HeaderValue::from_static("Bearer refreshed-token"),
        };

        let mut headers = HeaderMap::new();
        headers.insert(header::AUTHORIZATION, value);

        Ok(AuthenticationAttempt::new(headers, generation)
            .with_binding(format!("credential-generation-{generation}")))
    }
}

let authentication = Authentication::new(RotatingTokens);
```

The rejected-attempt refresh is independent of resilience retries.
OpenAI Responses additionally requires the refreshed attempt to retain
the original non-secret binding before replaying continuation state.

### Optional resilience

All provider configurations can opt into a shared retry and timeout
policy:

```rust
use std::time::Duration;
use agentkit_http::ResilienceConfig;
use agentkit_provider_openai::{
    OpenAIChatCompletionsAdapter, OpenAIConfig,
};

let resilience = ResilienceConfig {
    max_retries: 3,
    retry_budget: Duration::from_secs(60),
    attempt_timeout: Some(Duration::from_secs(30)),
    stream_idle_timeout: Some(Duration::from_secs(30)),
    initial_backoff: Duration::from_millis(200),
    max_backoff: Duration::from_secs(10),
};

let adapter = OpenAIChatCompletionsAdapter::new(
    OpenAIConfig::new("sk-openai", "gpt-4o")
        .with_resilience(resilience),
)?;
```

`resilience: None` preserves the existing no-timeout, single-attempt
behavior. `Some(ResilienceConfig::default())` enables bounded retries
and timeouts; it is not equivalent to omission.

Authentication schemes remain provider-specific:

| Providers | Authentication behavior |
|---|---|
| OpenAI, OpenRouter, Groq, Mistral, Baseten, Cerebras | Bearer by
default |
| Anthropic | `x-api-key` via `new`, bearer via `with_auth_token` |
| Ollama, vLLM | Optional; unauthenticated by default |

For Anthropic, use the constructor matching the intended scheme:

```rust
use agentkit_provider_anthropic::AnthropicConfig;

let api_key = AnthropicConfig::new(
    "sk-ant",
    "claude-sonnet-4-6",
    4096,
)?; // x-api-key

let bearer = AnthropicConfig::with_auth_token(
    "oauth-token",
    "claude-sonnet-4-6",
    4096,
)?; // Authorization: Bearer
```

Protected Ollama and vLLM deployments can now opt in without changing
local defaults:

```rust
use agentkit_provider_ollama::OllamaConfig;
use agentkit_provider_vllm::VllmConfig;

let local = OllamaConfig::new("llama3.2");
let protected = VllmConfig::new("Qwen/Qwen3-8B")
    .with_api_key("server-token");
```

### Separate OpenAI schema adapters

Chat Completions and Responses remain separate request codecs and stream
state machines. The explicit Chat Completions name is
`OpenAIChatCompletionsAdapter`; the historical `OpenAIAdapter` alias
remains available.

```rust
use agentkit_provider_openai::{
    OpenAIChatCompletionsAdapter, OpenAIConfig,
    OpenAIResponsesAdapter, OpenAIResponsesConfig,
};

let chat = OpenAIChatCompletionsAdapter::new(
    OpenAIConfig::new("sk-openai", "gpt-4o")
        .with_max_completion_tokens(4096),
)?;

let responses = OpenAIResponsesAdapter::new(
    OpenAIResponsesConfig::new("sk-openai", "gpt-5")
        .with_reasoning_effort("medium")
        .with_max_output_tokens(4096),
)?;
```

`OpenAIResponsesConfig::new(authentication, model)` follows the existing
`OpenAIConfig` argument order. Profile-specific constructors are
model-first:

```rust
let public = OpenAIResponsesConfig::public(
    "gpt-5",
    "sk-openai",
);

let private = OpenAIResponsesConfig::chatgpt_private(
    "gpt-5-codex",
    Authentication::new(RotatingTokens),
)
.with_originator("my-client")
.with_user_agent("my-client/1.0");
```

The Responses adapter supports configurable endpoints, request policy,
limits, attribution, encrypted reasoning continuation, idempotency,
response-size bounds, and private ChatGPT request/stream behavior
without embedding any consumer-specific metadata or persistence formats.

### Typed response-attempt supersession

OpenAI Responses retries only before visible output by default. A
consumer that can discard an already-rendered attempt may opt into
post-output recovery with a typed capability:

```rust
use agentkit_loop::{ModelTurnEvent, SessionConfig};

let session = SessionConfig::new("session-1")
    .with_response_attempt_supersession();

fn retain_latest_attempt(
    events: impl IntoIterator<Item = ModelTurnEvent>,
) -> Vec<ModelTurnEvent> {
    let mut current_attempt = Vec::new();

    for event in events {
        match event {
            ModelTurnEvent::ResponseAttemptSuperseded => {
                current_attempt.clear();
            }
            other => current_attempt.push(other),
        }
    }

    current_attempt
}
```

Opting in asserts that the consumer can discard all deltas, tool calls,
usage, and reconstruction state from the failed attempt. AgentKit emits
`ResponseAttemptSuperseded` after the failed attempt and before any
replacement output. Without the capability, a failure after visible
output is returned instead of replayed.

Author: danielkov

Cargo.lock

@@ -122,9 +122,25 @@ Shell:
 
 The filesystem crate also supports session-scoped read-before-write enforcement through `FileSystemToolResources` and `FileSystemToolPolicy`.
 
+## Provider authentication and resilience
+
+Provider configs use `agentkit_http::Authentication` as their first-class
+credential type. For Baseten, Cerebras, Groq, Mistral, OpenAI, OpenRouter, and
+authenticated Ollama/vLLM endpoints, passing a bare string to an authentication
+argument is shorthand for bearer authentication. Custom refresh-capable
+credentials can be installed with `.with_authentication_provider(...)`.
+Anthropic is the exception: `AnthropicConfig::new(...)` sends `x-api-key`, while
+`AnthropicConfig::with_auth_token(...)` explicitly selects a bearer auth token.
+Ollama and vLLM authentication is optional.
+
+Provider resilience is also opt-in. Configs store
+`Option<agentkit_http::ResilienceConfig>` and default to `None`; call
+`.with_resilience(...)` to enable retries and timeouts. Leaving it as `None`
+preserves the existing single-attempt behavior.
+
 ## Quick start
 
-1. Set your OpenRouter API key and model — either through environment variables or directly in code via `OpenRouterConfig::new(api_key, model)`.
+1. Set your OpenRouter API key and model — either through environment variables or directly in code via `OpenRouterConfig::new(authentication, model)`.
 2. Run one of the examples.
 
 Example commands:

README.md

@@ -254,10 +254,17 @@ pub enum ModelTurnEvent {
     Delta(Delta),
     ToolCall(ToolCallPart),
     Usage(Usage),
+    ResponseAttemptSuperseded,
     Finished(ModelTurnResult),
 }
 ```
 
+`ResponseAttemptSuperseded` is capability-gated. An adapter emits it after events
+from a failed visible attempt and before any replacement-attempt events. The loop
+forwards it as `AgentEvent::ResponseAttemptSuperseded`. A consumer that enables
+`SessionConfig::with_response_attempt_supersession()` must discard all deltas,
+tool calls, usage updates, and reconstruction state from the preceding attempt.
+
 ## Building an adapter from scratch
 
 To see what the traits require, consider a hypothetical model provider that does not use the OpenAI format. Suppose "AcmeAI" has a proprietary REST API:
@@ -287,12 +294,14 @@ No `messages` array. No `choices` wrapper. No `tool_calls`. A completely differe
 ```rust
 pub struct AcmeAdapter {
     client: Client,
-    api_key: String,
+    authentication: Authentication,
+    resilience: Option<ResilienceConfig>,
 }
 
 pub struct AcmeSession {
     client: Client,
-    api_key: String,
+    authentication: Authentication,
+    resilience: Option<ResilienceConfig>,
 }
 
 #[async_trait]
@@ -302,7 +311,8 @@ impl ModelAdapter for AcmeAdapter {
     async fn start_session(&self, _config: SessionConfig) -> Result<AcmeSession, LoopError> {
         Ok(AcmeSession {
             client: self.client.clone(),
-            api_key: self.api_key.clone(),
+            authentication: self.authentication.clone(),
+            resilience: self.resilience.clone(),
         })
     }
 }
@@ -348,10 +358,15 @@ impl ModelSession for AcmeSession {
             "config": { "temperature": 0.5, "max_tokens": 256 },
         });
 
-        let resp: AcmeResponse = self.client
+        let authentication = self.authentication.authenticate(None).await
+            .map_err(|e| LoopError::Provider(e.to_string()))?;
+        let mut request = self.client
             .post("https://api.acme.ai/v1/generate")
-            .bearer_auth(&self.api_key)
-            .json(&body)
+            .json(&body);
+        for (name, value) in authentication.headers() {
+            request = request.header(name, value);
+        }
+        let resp: AcmeResponse = request
             .send().await
             .map_err(|e| LoopError::Provider(e.to_string()))?
             .json().await
@@ -619,9 +634,9 @@ This is the complete provider. All of the transcript conversion, tool call seria
 
 Not all OpenAI-compatible providers are identical. The three hooks exist for providers that need to customise the standard request/response flow.
 
-OpenRouter uses all three:
+OpenRouter uses all three, while exposing its first-class credential through `authentication()`:
 
-1. **`preprocess_request`** — adds bearer auth, `X-Title`, and `HTTP-Referer` headers
+1. **`preprocess_request`** — adds `X-Title` and `HTTP-Referer` headers
 2. **`preprocess_response`** — the API sometimes returns HTTP 200 with an error payload instead of a proper error status; the hook parses these and converts them to errors before the adapter attempts normal deserialization
 3. **`postprocess_response`** — extracts the `cost` field from the usage object (OpenRouter-specific, not part of the standard format) and adds `openrouter.model` and `openrouter.refusal` to the item metadata
 
@@ -633,11 +648,15 @@ impl CompletionsProvider for OpenRouterProvider {
     fn endpoint_url(&self) -> &str { &self.base_url }
     fn config(&self) -> &OpenRouterRequestConfig { &self.request_config }
 
+    fn authentication(&self) -> Option<Authentication> {
+        Some(self.authentication.clone())
+    }
+
     fn preprocess_request(
         &self,
         builder: agentkit_http::HttpRequestBuilder,
     ) -> agentkit_http::HttpRequestBuilder {
-        let mut builder = builder.bearer_auth(&self.api_key);
+        let mut builder = builder;
         if let Some(app_name) = &self.app_name {
             builder = builder.header("X-Title", app_name);
         }

book/src/ch01-model-adapter.md

@@ -49,18 +49,23 @@ pub enum ItemKind {
 
 The variants are ordered: `System < Developer < User < Assistant < Tool < Context`. This ordering is used by compaction strategies that need to sort or prioritise items by role.
 
-Role mapping to provider wire formats:
-
-| agentkit `ItemKind` | OpenAI role   | What it carries                    |
-| ------------------- | ------------- | ---------------------------------- |
-| `System`            | `"system"`    | Hardcoded application instructions |
-| `Developer`         | `"system"`    | Developer-level instructions       |
-| `User`              | `"user"`      | End-user messages                  |
-| `Assistant`         | `"assistant"` | Model-generated text + tool calls  |
-| `Tool`              | `"tool"`      | Tool execution results             |
-| `Context`           | `"system"`    | Project context (AGENTS.md, etc.)  |
-
-System, Developer, and Context all map to `"system"` in the OpenAI wire format, but they carry different semantic intent. The distinction matters for compaction: system items are never trimmed, context items may be refreshed, and developer items sit between the two. Collapsing them into a single kind would lose information that compaction strategies need.
+Role mapping depends on the OpenAI API and profile. Chat Completions uses:
+
+| agentkit `ItemKind` | Chat Completions role | What it carries                    |
+| ------------------- | --------------------- | ---------------------------------- |
+| `System`            | `"system"`            | Hardcoded application instructions |
+| `Developer`         | `"developer"`         | Developer-level instructions       |
+| `User`              | `"user"`              | End-user messages                  |
+| `Assistant`         | `"assistant"`         | Model-generated text + tool calls  |
+| `Tool`              | `"tool"`              | Tool execution results             |
+| `Context`           | `"system"`            | Project context (AGENTS.md, etc.)  |
+
+For the Responses API, the public profile keeps System and Context items as
+`system`; the private profile sends both as `developer`. Context content is
+encoded unchanged, without consumer-specific prose. These kinds retain distinct
+semantic intent even when a provider maps them to the same role. The distinction
+matters for compaction: system items are never trimmed, context items may be
+refreshed, and developer items sit between the two.
 
 ### Why item-based, not message-based
 

book/src/ch03-transcript-model.md

@@ -105,6 +105,7 @@ pub enum ModelTurnEvent {
     Delta(Delta),
     ToolCall(ToolCallPart),
     Usage(Usage),
+    ResponseAttemptSuperseded,
     Finished(ModelTurnResult),
 }
 ```
@@ -129,11 +130,21 @@ Turn event timeline:
 
   Usage(Usage)              ← token counts
 
+  ResponseAttemptSuperseded ← optional; invalidates every event above
+  Delta(...)                 ← replacement attempt starts after the marker
+
   Finished(ModelTurnResult) ← always last
 ```
 
 `Finished` always comes last. `Usage` typically comes just before `Finished` but some providers interleave it with deltas. `ToolCall` events represent fully assembled tool calls — the adapter has already accumulated the streaming chunks internally.
 
+`ResponseAttemptSuperseded` is emitted only when the consumer enabled
+`SessionConfig::with_response_attempt_supersession()`. It appears after the failed
+visible attempt and before replacement output. The loop resets its attempt-local
+tool-call and usage state and forwards `AgentEvent::ResponseAttemptSuperseded`;
+consumers must discard every delta, tool call, usage update, and reconstruction
+state from the preceding attempt.
+
 ### ModelTurnResult
 
 ```rust

book/src/ch05-model-adapter.md

@@ -13,6 +13,7 @@ pub struct SessionConfig {
     pub session_id: SessionId,
     pub metadata: MetadataMap,
     pub cache: Option<PromptCacheRequest>,
+    pub consumer_capabilities: SessionConsumerCapabilities,
 }
 
 pub struct TurnRequest {
@@ -83,16 +84,12 @@ The simplest place to configure caching is the session:
 
 ```rust
 let mut driver = agent
-    .start(SessionConfig {
-        session_id: SessionId::new("coding-agent"),
-        metadata: MetadataMap::new(),
-        cache: Some(PromptCacheRequest {
-            mode: PromptCacheMode::BestEffort,
-            strategy: PromptCacheStrategy::Automatic,
-            retention: Some(PromptCacheRetention::Short),
-            key: None,
-        }),
-    })
+    .start(SessionConfig::new("coding-agent").with_cache(PromptCacheRequest {
+        mode: PromptCacheMode::BestEffort,
+        strategy: PromptCacheStrategy::Automatic,
+        retention: Some(PromptCacheRetention::Short),
+        key: None,
+    }))
     .await?;
 ```
 
@@ -225,16 +222,12 @@ This makes caching visible to reporters and host-side cost accounting without ex
 For most hosts, start here:
 
 ```rust
-SessionConfig {
-    session_id: SessionId::new("demo"),
-    metadata: MetadataMap::new(),
-    cache: Some(PromptCacheRequest {
-        mode: PromptCacheMode::BestEffort,
-        strategy: PromptCacheStrategy::Automatic,
-        retention: Some(PromptCacheRetention::Short),
-        key: None,
-    }),
-}
+SessionConfig::new("demo").with_cache(PromptCacheRequest {
+    mode: PromptCacheMode::BestEffort,
+    strategy: PromptCacheStrategy::Automatic,
+    retention: Some(PromptCacheRetention::Short),
+    key: None,
+})
 ```
 
 Then reach for explicit breakpoints only when you need to control exact cache boundaries.