--- id: SMH-PLAN-AIAGD002 type: plan title: "Provider and OAuth Plugins" spec: SMH-SPEC-PLUG0001 status: approved depends_on: [] --- # Provider and OAuth Plugins ## Outcome Supported provider connections bind to unprivileged protocol plugins. Connections share implementations where wire behavior matches; provider-specific plugins cover behavioral specializations. Users log in with a Z.ai key and with OpenAI, Anthropic, and Google subscriptions; provider-specific code is gone from the core. ## Scope Protocol plugins, host-owned provider connections and models.dev catalog integration, the shared OAuth plugin, plugin-to-plugin dependencies, and core adapter removal. Host surface and scaffolding come from the harness plan. ## Behaviors Ordered by delivery value. 1. **Catalog-backed Z.ai connections**: separate API and Coding Plan connections share an OpenAI-compatible protocol plugin; key credential from the auth store or official environment; one eval turn runs end to end without native vendor dispatch. Host catalog normalization, explicit compatible bindings, immutable configuration, provenance, and read-only plugin catalog access accompany this slice. An explicit Cargo task refreshes the reviewed models.dev build snapshot; runtime refresh is bounded, cancellable, cached, and atomically published without widening grants. 2. **OAuth plugin**: device or localhost-redirect flows through net-scope effects; tokens cross the secret-proxy boundary to the auth store; renewal refreshes before dispatch. 3. **Plugin dependency**: provider plugins declare a dependency on the OAuth plugin's major-versioned module contract; the harness validates the complete set before publication; missing or ambiguous bindings fail at consumption with sorted candidates. 4. **OpenAI connections**: subscription login via the OAuth plugin plus key support; explicitly bind each connection to its supported protocol implementation and catalog capabilities. 5. **Anthropic connections**: subscription login plus key support; Anthropic wire behavior lives in its protocol plugin, model data in the host catalog. 6. **Google connections**: subscription login plus key support; Google wire behavior lives in its protocol plugin, using the same catalog and registration path. 7. **Core adapter removal**: native vendor decoders and vendor catalogs are deleted; mux routes plugin-registered providers; conformance fixtures validate plugin streams against recorded transcripts. ## Login surface ```mermaid flowchart LR U["smith login --provider VENDOR"] --> O{"flow?"} O -- key --> K["auth store (stdin secret)"] O -- subscription --> P["oauth plugin flow"] P --> N["net-scope http"] N --> SP["secret-proxy exchange"] SP --> S["auth store"] K --> R["resolve before dispatch"] S --> R ``` ## Plan dependencies ```mermaid flowchart LR PLUG["PLUG0001 harness + scaffolding"] --> Z["zai plugin"] Z --> OA["oauth plugin"] OA --> DEP["plugin dependency validation"] DEP --> OAI["openai"] DEP --> ANT["anthropic"] DEP --> GOO["google"] OAI --> RM["remove core adapters"] ANT --> RM GOO --> RM ``` ## Interfaces - `plugins/protocol-openai-compatible` plus protocol guests required by OpenAI, Anthropic, and Google wire behavior. - Host-owned connection definitions, models.dev catalog snapshots, typed config resolution, and read-only WIT catalog access. - `plugins/oauth`: exports the credential-source module contract. - `smith login`: vendor login command over key or subscription flows. ## Verification - Each vendor completes one eval round using only its plugin-registered provider. - Subscription credentials renew before expiry without re-login. - A provider plugin missing its OAuth dependency fails at consumption with the consumer and candidates named. - No native vendor decoder remains; conformance validates each plugin stream against recorded transcripts. - Credential plaintext never appears in logs, traces, replay, or plugin diagnostics. - Embedded built-in provider artifacts update without a smith rebuild in dev configurations. ## Stop conditions - A vendor requires an effect absent from the public world. - OAuth flows cannot complete without ambient capabilities beyond net-scope and secret-proxy. - Plugin dependency validation cannot reject incomplete sets atomically.