@x-otto/provider 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,103 @@
+# @otto/provider
+
+> Provider-neutral protocol types, chat-completions protocol base, OAuth templates, stream error classification, and stream recording/replay — the LLM provider insertion point package.
+
+`@otto/provider` is the public interface package for LLM provider implementations. It provides the `ProviderStream`/`ProviderFactory`/`StreamContext` contract types, the chat-completions protocol base (shared by OpenAI-compatible and custom providers), OAuth login/refresh templates (PKCE, device-flow), stream error classification, stream recording/replay for diagnostics, and request header assembly.
+
+**Zero vendor implementations**: all concrete provider implementations live in extensions/plugins (see `extensions/plugin-otto-wire-protocols` for standard wire protocols, `extensions/plugin-github-copilot` for the Copilot custom provider). This package provides only the insertion point contracts and shared tooling.
+
+## Installation
+
+```bash
+pnpm add @otto/provider
+```
+
+## Usage
+
+```ts
+import { streamChatCompletions } from '@otto/provider'
+import { buildChatCompletionsBody } from '@otto/provider'
+import { sanitizeToolRoundtrips } from '@otto/provider'
+import { classifyStreamError, isAuthError } from '@otto/provider'
+import { buildRequestHeaders } from '@otto/provider'
+import { recordStream, replayStream } from '@otto/provider'
+
+// Streaming chat completions
+const events = streamChatCompletions({
+  model,
+  messages,
+  tools,
+  signal,
+})
+
+// Build request body
+const body = buildChatCompletionsBody({
+  model,
+  messages: sanitizeToolRoundtrips(messages),
+  tools,
+})
+
+// Classify errors
+try { /* ... */ } catch (err) {
+  if (isAuthError(err)) { /* handle auth */ }
+  if (isContextOverflowError(err)) { /* compact context */ }
+  const cls = classifyStreamError(err)
+}
+
+// Record + replay streams (diagnostics)
+const recording = recordStream(streamEvents, { model, messages })
+// ...save recording to disk...
+const replay = replayStream(loadRecording('path/to/recording.json'))
+```
+
+## API
+
+### Chat Completions Protocol Base
+- `streamChatCompletions(params)` — SSE streaming loop for chat-completions-compatible APIs
+- `buildChatCompletionsBody(params)` — construct request body from model/messages/tools
+- `buildChatCompletionsMessages(messages, model)` — prepare messages array for the body
+- `clampThinkingLevel(level)` — normalize thinking effort to known levels
+- `mapChatFinishReason(reason)` — map native finish reason → canonical StopReason
+
+### Protocol-Neutral Primitives
+- `sanitizeToolRoundtrips(messages)` — deduplicate tool roundtrips, fix placement
+- `initStreamUsage()` / `parseToolArgumentsWithStatus(items, warn)` — stream state management
+- `assembleAssistantMessage(state, meta)` — build final AssistantMessage from accumulated state
+- `sanitizeSurrogates(text)` / `toJsonSchema(schema)` — encoding utilities
+- `assertSystemNotificationPlacement(messages)` / `degradedSystemNotificationText(text)` — message ordering
+
+### OAuth Templates
+- `PKCEOAuthTemplate(params)` — PKCE flow template (used by Anthropic, OpenAI Codex plugins)
+- `DeviceFlowOAuthTemplate(params)` — device code flow template (used by GitHub Copilot plugin)
+- `createPkcePair()` / `generateVerifier()` / `generateChallenge()` / `generateState()` — PKCE primitives
+- `startLoopbackServer(options)` — OAuth callback server
+- `extractJwtClaim(token)` — JWT decoding utility
+
+### Stream Error Classification
+- `classifyStreamError(error)` → `StreamErrorClass` — unified error classification
+- `isContextOverflowError(error)` — 413 / "prompt too long" detection
+- `isNetworkDisconnectError(error)` — ECONNRESET / socket hang-up detection
+- `isAuthError(error)` — 401/403 auth failure detection
+- `classifyAuthErrorType(error)` → `AuthErrorType` — specific auth failure subtype
+- `extractRetryAfterMs(error)` — parse Retry-After header or rate limit info
+- `extractAnthropicRateLimit(headers)` — parse Anthropic-specific rate limit headers
+
+### Rate Limit & Usage Headers
+- `extractStandardRateLimitHeaders(headers)` — parse `x-ratelimit-*` headers from any provider
+- `buildRequestHeaders(sources)` — assemble outbound request headers with 5-tier priority
+
+### Stream Recording & Replay (RFC-200)
+- `recordStream(stream, meta)` — capture StreamEvent sequence to Recording
+- `loadRecording(path)` / `saveRecording(recording, path)` — persist recordings
+- `replayStream(recording, options?)` — replay a recording as an AsyncIterable
+- `ReplayProviderStream` / `createReplayProviderFactory(buildReplayModel)` — replay as a ProviderStream
+- `recordingsDir()` — default recordings directory path
+
+## Dependencies
+
+- Internal: `@otto/interchange` (protocol types), `@otto/shared` (logger, error types, header utils)
+- External: none (only Node.js builtins + `@otto/*` internal packages)
+
+## Related
+
+- [Architecture](./ARCHITECTURE.md)