---
id: SMH-PLAN-AIAG0001
type: plan
title: "Provider Runtime and Agent Loop"
spec: SMH-SPEC-SPEC0001
status: approved
depends_on: [SMH-PLAN-CORE0001]
---

# Provider Runtime and Agent Loop

## Entry

- Shared stream, tool, error, session, and trace contracts are stable.
- Provider-free tool events persist correctly.

## Decisions

- One normalized stream vocabulary is the provider contract; vendor wire shapes stay inside adapters, so later adapters are additive (SMH-RESEARCH-AIAGD001).
- The stream abstraction lands in `smith` before the first adapter.
- Stream conformance fixtures are provider-agnostic; the first adapter proves the kit, later adapters plug into it.

## Order

1. Add `StreamFn` request and stream types to `smith`.
2. Add `smith-ai` provider adapters that normalize deltas, tool calls, usage, stop reasons, errors, and cancellation.
3. Add explicit model capability metadata and request validation.
4. Add the reviewed offline catalog and deterministic alias, group, and account resolution.
5. Add credential resolution, readiness checks, renewable credentials, and concurrent update safety.
6. Add cancellable catalog refresh with cached fallback and generation-checked publication.
7. Build the provider-agnostic conformance kit and prove one OpenAI-compatible adapter against fragmented, malformed, incomplete, and non-stream error fixtures.
8. Add required Anthropic, OpenAI, and Google adapter coverage through the same normalized boundary.
9. Add the `smith-core` agent loop with ordered turn, message, tool, retry, and settled events.
10. Add steering, follow-up, compaction, cost, secret substitution, bounded retry, and failover behavior.
11. Expose eval and LF-delimited JSON-RPC through `smith-cli` and `smith-harness`.

## Interfaces

- `smith-ai::provider`: vendor transport to normalized stream.
- `smith-ai::models`: coherent catalog snapshots and capabilities.
- `smith-ai::auth`: credential state without context exposure.
- `smith-core::agent`: provider-independent turns and ordered effects.
- `smith-harness`: shared eval and RPC runtime assembly.

## Verification

- A mock provider completes a tool-using turn with correctly paired durable events.
- Every stream has one terminal outcome; malformed terminal sequences fail explicitly.
- Requests cannot use unadvertised model capabilities.
- Stale or cancelled catalog refreshes cannot replace newer state.
- Offline startup retains a usable catalog.
- Concurrent credential changes preserve unrelated providers.
- Injected messages never split tool calls from results.
- Compaction preserves queued-message mode and rejects incomplete summaries.
- RPC deltas assemble to the authoritative final message and errors retain request IDs.

## Exit

Eval and RPC run complete provider-backed agent turns through one runtime without vendor details crossing the provider boundary.

## Stop conditions

- Provider fields are required by core behavior.
- Catalog authority or refresh conflict policy is unresolved.
- Event ordering cannot represent a provider edge case without ambiguity.