@easbot/llm 0.3.19

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 houjallen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,419 @@
+# @easbot/llm
+
+English | [中文](./README.md)
+
+`@easbot/llm` is the **AI model aggregation layer** of the EASBot ecosystem. It handles dynamic loading of multi-vendor SDKs, model routing, configuration management, and high-level Model Provider capability wrapping. It provides business packages (agent / codebase / memory / note / skills / gateway) with a unified LLM calling abstraction, avoiding the duplication of provider routing, auth management, and error normalization across every tool package.
+
+## Current Status (after V4 refactor)
+
+This package has evolved from an early placeholder of `@easbot/types` into a production-grade AI gateway layer that hosts two core modules: `provider/*` and `model/*`:
+
+- ✅ **`src/provider/`** (19 files): complete industrial-grade provider abstraction
+  - `Provider` namespace — 25+ built-in SDK (OpenAI / Anthropic / Azure / Bedrock / Vertex / OpenRouter / Copilot / Ollama / local models, etc.) dynamic loaders, `ModelsDev` catalog merging, model caching, SDK instance pooling
+  - `ProviderError` namespace — APICallError parsing (including 25+ "context overflow" regex patterns)
+  - `ProviderAuth` namespace — OAuth + API key dual-track authentication
+  - `ProviderTransform` namespace — model variant / tool / limit handling
+  - `ModelsDev` namespace — models.dev catalog zod schema + loading + remote refresh
+  - `definition.ts` — DEFAULT_ENABLED_PROVIDERS whitelist + CUSTOM_PROVIDER_DEFINITIONS local SDK snapshot + PROVIDER_DISPLAY_NAMES friendly name mapping
+  - `sdk/copilot/` — self-developed GitHub Copilot-compatible SDK (chat + responses + 6 tools)
+- ✅ **`src/model/`** (4 namespaces): high-level Model Providers
+  - `RerankProvider` namespace — LLM-driven document reranking (unified with Memory hybrid search weights)
+  - `GraphProvider` namespace — extract entities and relations from unstructured text (11 EntityType + 9 RelationType)
+  - `SummaryProvider` namespace — note / memory summarization (LLM-based)
+- ✅ **`src/config/`** (V3 new): independent LLM Config module, mirroring `packages/gateway/src/config/` pattern
+  - `LLMConfig / ProviderConfig / ProviderAuthMethod` — zod schemas (standalone usable, or as source-of-truth for injected Config)
+  - `Config` namespace — `get()` / `provider(id)` (prefer injected, fall back to local loader)
+- ✅ **`src/interfaces.ts`** (V3 new / V4 simplified): **Adapter Registry** + Env / Flag namespace
+  - 4 Provider interfaces (`IConfigProvider` / `IInstanceProvider` / `IGlobalPathProvider` / `IInstallationProvider`; Auth moved to `@easbot/utils.Auth`)
+  - `setAdapterRegistry(...)` — one-shot injection at agent-package startup, **completely decoupling** this package from agent's internal modules
+  - `getI<X>Provider()` convenient accessors — fail-fast throws when not registered (**no silent degradation**)
+  - `readEnvString / readFlagBool / readFlagNumber` — static readers, avoiding dependency on injection
+  - `Env / Flag` namespaces — static literals mirroring `process.env` (for IDE hints / doc generation / config introspection)
+- ✅ **`src/index.ts`** — aggregate export entry (4 provider namespaces + 3 model namespaces + self-developed Copilot SDK + 3 constants + Config / interfaces + AdapterRegistry + 4 Provider interfaces)
+
+## Core Features
+
+- **25+ built-in AI SDK dynamic loading**: lazy `import()` to avoid bundle bloat
+- **Three-layer data source fusion**: models.dev remote catalog + build-time snapshot + local CUSTOM_PROVIDER_DEFINITIONS (for ollama / easbot-local which don't appear on models.dev)
+- **Unified Provider namespace**: `Provider.list() / getModel() / parseModel()` — one-liner calls, decoupled from concrete SDKs
+- **OAuth + API key dual-track**: `ProviderAuth` namespace manages OAuth flow / API key persistence / injection into SDK options
+- **Context Overflow auto-detection**: cross-vendor unified "context exceeded" semantics (25+ regex patterns + 4 HTTP status fallbacks)
+- **Self-developed GitHub Copilot-compatible SDK**: complete chat + responses API + 6 tools (code-interpreter / file-search / web-search / image-generation / local-shell / web-search-preview)
+- **Persistent model cache**: build-time generated `models-snapshot.ts`, runtime prefers local to avoid cold-start network calls
+- **Minimal aggregate export**: a single `@easbot/llm` import line gives you 5+3 namespaces + self-developed SDK + key constants
+
+## Installation
+
+```bash
+pnpm add @easbot/llm
+```
+
+## Quick Start
+
+### 1. List all configured providers
+
+```typescript
+import { Provider } from '@easbot/llm';
+
+const allProviders = await Provider.list();
+// { openai: { id, name, source, env, models, ... }, anthropic: {...}, ... }
+```
+
+### 2. Get a specific model (routed via `provider/model` string)
+
+```typescript
+import { Provider } from '@easbot/llm';
+
+const gpt4 = await Provider.getModel('openai/gpt-4');
+// gpt4: LanguageModelV3 (AI SDK v6 spec)
+
+const embed = await Provider.getModel('openai/text-embedding-3-small');
+// embed: EmbeddingModelV3
+
+const rerank = await Provider.getModel('easbot-local/rerank-proxy');
+// rerank: RerankingModelV3
+```
+
+### 3. Parse model ID (safe split, no throws)
+
+```typescript
+import { Provider } from '@easbot/llm';
+
+const { providerId, modelId } = Provider.parseModel('openai/gpt-4o');
+// { providerId: 'openai', modelId: 'gpt-4o' }
+```
+
+### 4. Parse API errors (with context overflow detection)
+
+```typescript
+import { ProviderError, APICallError } from 'ai';
+
+try {
+  await someProvider.doCall(...);
+} catch (e) {
+  if (e instanceof APICallError) {
+    const parsed = ProviderError.parseAPICallError({ providerId: 'openai', error: e });
+    if (parsed.type === 'context_overflow') {
+      // UI: "Context exceeded, please shorten input or switch model"
+    }
+  }
+}
+```
+
+### 5. Direct calls to high-level Model Providers
+
+```typescript
+import { RerankProvider, GraphProvider, SummaryProvider } from '@easbot/llm';
+
+// Document reranking
+const reranked = await RerankProvider.rerank({
+  query: '...',
+  documents: ['...', '...'],
+});
+
+// Graph entity extraction
+const graph = await GraphProvider.generateGraph({
+  chunks: ['chunk1...', 'chunk2...', '...'],  // any-length array
+  prompt: { maxChunks: 5, maxConcurrency: 3 }, // v0.8: per-call slicing + 3 concurrent
+});
+// graph.entities / relations / summary are directly ingestable
+```
+
+**v0.8 behavior contract** (`packages/llm/src/model/graph.ts`):
+
+- **All chunks are attempted**: chunks are sliced by `prompt.maxChunks` (default 5) into multiple groups; each group triggers one LLM call. No more v0.7-style hard truncation to the first 5 chunks.
+- **Chunk-level 3-way concurrency**: multiple groups run via lightweight semaphore (`prompt.maxConcurrency`, default 3) to avoid triggering provider rate limits.
+- **Local failure tolerance**: a single group's LLM failure only loses that group's result; others continue. One failure no longer wipes the entire document's KG.
+- **Boundary-aware truncation**: overlong chunks are further split via `splitByBoundary` (nearest `\n\n` / `\n` / whitespace), ensuring entity names are never cut in half.
+
+```typescript
+// Note knowledge base summarization
+const summary = await SummaryProvider.summarizeNote({
+  query: '...',
+  chunks: [...],
+});
+```
+
+### 6. Text embedding (EmbeddingProvider)
+
+```typescript
+import { EmbeddingProvider } from '@easbot/llm';
+
+// Single-text embedding — returns EmbedOutput (with embedding + usage.tokens)
+const single = await EmbeddingProvider.embedText({ value: 'some text' });
+// single.embedding: number[] (default bge-base-zh-v1.5 outputs 512 dimensions)
+// single.usage.tokens: number
+
+// Batch embedding (recommended: one API call beats N aiEmbed calls)
+const batch = await EmbeddingProvider.embedTexts({ values: ['a', 'b', 'c'] });
+// batch.embeddings: number[][] (one-to-one with values)
+// batch.usage.tokens: number
+
+// Explicit model override (skips Provider.defaultModel)
+import { Provider } from '@easbot/llm';
+const customModel = Provider.parseModel('openai/text-embedding-3-small');
+const r = await EmbeddingProvider.embedText({ value: 'hi', model: customModel });
+```
+
+### 7. Use the self-developed GitHub Copilot SDK
+
+```typescript
+import { createOpenaiCompatible, openaiCompatible } from '@easbot/llm';
+
+const copilot = createOpenaiCompatible({
+  apiKey: process.env.GITHUB_TOKEN,
+});
+const model = copilot('gpt-4o');
+// Or use the default instance
+const model2 = openaiCompatible('gpt-4o');
+```
+
+## Top-level Export List
+
+```typescript
+// Provider core namespaces
+export * as Provider from './provider/provider';
+export * as ProviderError from './provider/error';
+export * as ProviderAuth from './provider/auth';
+export * as ProviderTransform from './provider/transform';
+export * as ModelsDev from './provider/models';
+
+// Provider constants
+export {
+  DEFAULT_ENABLED_PROVIDERS,
+  CUSTOM_PROVIDER_DEFINITIONS,
+  PROVIDER_DISPLAY_NAMES,
+} from './provider/definition';
+
+// Top-level functions
+export { initModelsRefresh } from './provider/models';
+
+// Self-developed GitHub Copilot SDK
+export {
+  createOpenaiCompatible,
+  openaiCompatible,
+} from './provider/sdk/copilot';
+export type {
+  OpenaiCompatibleProvider,
+  OpenaiCompatibleProviderSettings,
+  OpenaiCompatibleModelId,
+} from './provider/sdk/copilot';
+
+// High-level Model Provider namespaces
+export * as RerankProvider from './model/rerank';
+export * as GraphProvider from './model/graph';
+export * as SummaryProvider from './model/summary';
+export * as EmbeddingProvider from './model/embedding';
+```
+
+**EmbeddingProvider public contract** (`packages/llm/src/model/embedding.ts`):
+
+- `embedText(input, abortSignal?) → Promise<EmbedOutput>`
+  - `EmbedOutput = { embedding: number[]; usage: { tokens: number } }`
+  - Empty `value` returns `{ embedding: [], usage: { tokens: 0 } }` **without** calling `ai.embed`
+- `embedTexts(inputs, abortSignal?) → Promise<EmbedBatchOutput>`
+  - `EmbedBatchOutput = { embeddings: number[][]; usage: { tokens: number } }`
+  - Empty `values` returns `{ embeddings: [], usage: { tokens: 0 } }` **without** calling `ai.embedMany`
+- Default model: `easbot-local/bge-base-zh-v1.5` (exported as `EmbeddingProvider.DEFAULT_MODEL`)
+- `model` input supports three forms: omitted → `Provider.defaultModel` chain; `Provider.Model` → `Provider.getEmbedding`; directly passing an `EmbeddingModel` instance (duck-typed via `specificationVersion`) → skip the Provider chain
+
+## Configuration Injection (migration guide for switching LLM implementation)
+
+After the V4 refactor, the `Provider` / `ModelsDev` / `ProviderAuth` / `ProviderTransform` namespaces are **fully decoupled** from the agent package via the **Adapter Registry** pattern — they no longer directly `import` any module from agent. All runtime dependencies are explicitly injected through 4 Provider interfaces (Auth moved to `@easbot/utils.Auth`).
+
+### 1. Adapter Registry overview
+
+The agent package calls `setAdapterRegistry(...)` once at startup, injecting all 4 Provider implementations:
+
+```typescript
+import {
+  setAdapterRegistry,
+  type AdapterRegistry,
+} from '@easbot/llm';
+
+// At the agent-package startup entry (e.g. before Instance.provide)
+setAdapterRegistry({
+  config: Config,                // IConfigProvider       — get / provider
+  instance: Instance,            // IInstanceProvider     — getDirectory / getWorktree
+  global: Global.Path,           // IGlobalPathProvider   — cache / data / config
+  installation: Installation,    // IInstallationProvider — getVersion
+  // V4: Auth has moved to `@easbot/utils.Auth`, no longer injected via AdapterRegistry.
+  // Internally the LLM package calls `import { Auth } from '@easbot/utils'` directly.
+} satisfies AdapterRegistry);
+```
+
+**When not registered, all `getI<X>Provider()` calls fail-fast with a descriptive error**:
+
+```
+[LLM] adapter 'config' (IConfigProvider) not registered.
+Call setAdapterRegistry({ config: ... }) before using LLM.
+```
+
+> Design intent: **no silent degradation**. Forgetting to inject throws immediately, avoiding production scenarios where "undefined config" silently breaks model routing.
+
+### 2. 4 Provider interface contracts
+
+| Interface | Methods | Original agent module | Purpose |
+|-----------|---------|----------------------|---------|
+| `IConfigProvider` | `get<T>(): Promise<T>` / `provider<T>(id): Promise<T \| undefined>` | `Config` | User `~/.config/easbot/config.json` llm block (whitelist / blacklist / variant override) |
+| `IInstanceProvider` | `getDirectory(): string` / `getWorktree(): string` | `Instance` | Instance directory + worktree paths |
+| `IGlobalPathProvider` | `cache: string` / `data: string` / `config: string` | `Global.Path` | Model snapshot cache / user data / global config directory |
+| `IInstallationProvider` | `getVersion(): string` | `Installation` | User-Agent / compatibility checks / version info |
+
+> **V4 change**: `IInstanceProvider.state(init)` and `IPluginProvider` have been **decomposed** (ADR 0071).
+> - Provider internal state caching now uses `@easbot/utils.lazyAsync(init)` (per-process singleton + explicit reset)
+> - Plugin registration uses module-level `_pluginAuthRegistry: Map<providerId, methods[]>` + `ProviderAuth.registerPluginAuthProvider()` entry injection
+
+### 3. LLM Config (standalone + integrated mode)
+
+The V3-new `src/config/` module mirrors `packages/gateway/src/config/`:
+
+- **Standalone**: directly read the `llm` block from `easbot.json` / `easbot.jsonc`
+- **Integrated**: when AdapterRegistry is injected, `Config.get()` prefers the injected implementation (let agent reuse)
+
+```typescript
+import { Config, LLMConfig } from '@easbot/llm';
+
+const cfg = await Config.get();           // injected or fallback loader
+const openaiCfg = await Config.provider('openai');
+
+// Schema validation (standalone)
+const parsed = LLMConfig.parse({
+  model: 'openai/gpt-4o',
+  provider: {
+    openai: {
+      npm: '@ai-sdk/openai',
+      options: { apiKey: 'sk-...' },
+    },
+  },
+});
+```
+
+### 4. Env / Flag namespace (mirroring process.env)
+
+`Flag` namespace and reader functions (`readEnvString` / `readFlagBool`) are still provided by the llm package. `Env` has been moved down to `@easbot/utils` — llm only re-exports it, callers may also import `Env` directly from `@easbot/utils`:
+
+```typescript
+import { Flag, readEnvString, readFlagBool } from '@easbot/llm';
+import { Env } from '@easbot/llm';        // equivalent to: import { Env } from '@easbot/utils'
+
+Flag.EASBOT_OUTPUT_TOKEN_MAX;       // numeric field, internally dynamic
+readEnvString('OPENAI_API_KEY');    // wraps process.env
+```
+
+### 5. Call-site migration table
+
+| Module | Pre-V3 | V3 | V4 (this refactor) |
+|--------|--------|----|----------------------|
+| `provider/auth.ts` | `Instance.state(...)` | `getIInstanceProvider().state(init)` | `lazyAsync(init)` + module-level `_pluginAuthRegistry` |
+| `provider/auth.ts` | `Auth.set(providerId, info)` | `Auth.set(...)` calls `@easbot/utils.Auth` directly (moved to utils) | `Auth.set(...)` calls `@easbot/utils.Auth` directly (moved to utils) |
+| `provider/auth.ts` | `Plugin.definitions()` | `getIPluginProvider().definitions()` | dependency removed; replaced by `registerPluginAuthProvider()` entry injection |
+| `provider/provider.ts` | `Instance.state(...)` | `getIInstanceProvider().state(init)` | `lazyAsync(createState)` (module-level per-process singleton) |
+| `config/loader.ts` | `Instance.state(...)` | `getIInstanceProvider().state(init)` | `lazyAsync(createState)` (module-level per-process singleton) |
+| `provider/models.ts` | `Global.Path.cache` | `getIGlobalPathProvider().cache` | (same as V3) |
+| `config/index.ts` | `Config.get()` | `getIConfigProvider().get()` | (same as V3) |
+
+**V4 refactor motivation**: `IInstanceProvider.state(init)` couples "caching" with "Instance abstraction",
+but state caching is fundamentally a **per-process singleton with explicit reset** — independent of
+`Instance.directory`. After sinking to `@easbot/utils.lazyAsync()`:
+- **Decoupled**: `IInstanceProvider` shrinks to 2 methods (`getDirectory` / `getWorktree`), single responsibility
+- **Unified**: every subsystem needing state caching (skills / mcp / plugin / etc.) reuses the same utility
+- **Testable**: `lazyAsync().reset()` is more direct than mocking a state factory
+
+### 6. Architectural advantages
+
+- **Zero hard-coded dependency**: `provider/*` and `model/*` files do not directly `import` any agent-package module
+- **Test-friendly**: tests use mock AdapterRegistry injection, no agent instance needed (`tests/setup.ts` provides a complete mock example)
+- **Multi-entry reuse**: same LLM implementation can be reused by web / cli / gateway / monitor — each just injects AdapterRegistry
+- **Clear contract**: fully aligned with the AdapterRegistry pattern used by ADR 0044 (skills) / 0045 (mcp) / 0046 (plugin)
+- **Fail-fast safety**: throws immediately on missing injection, no silent degradation
+
+## Provider Routing Priority
+
+`Provider` merges the provider registry in the following order during `createState`:
+
+1. **models.dev remote catalog**: at startup, if `Flag.EASBOT_MODELS_FETCH` is enabled, pull from `https://models.dev/api.json` (with local cache)
+2. **Build-time snapshot**: if remote fetch fails or cache is missing, use `models-snapshot.ts` (statically injected at build time)
+3. **CUSTOM_PROVIDER_DEFINITIONS**: local definition snapshot for self-developed SDKs (`@easbot/ollama-sdk` / `@easbot/local-model-sdk`)
+4. **config.provider**: override from user's `~/.config/easbot/config.json` provider block (e.g. custom baseURL / model options)
+5. **Environment variables + Auth persistence**: env vars + API keys persisted by `easbot auth login`
+6. **Plugin injection**: plugins can inject special providers via `plugin.auth.loader` (e.g. github-copilot's OAuth)
+7. **CUSTOM_LOADERS**: each provider's special initialization (anthropic headers, azure baseURL, amazon-bedrock AWS credentials, etc.)
+
+## Testing
+
+```bash
+pnpm --filter @easbot/llm test:run
+```
+
+Test files are in `tests/`:
+
+- `provider-smoke.test.ts` — validates pure constants in `definition.ts` (whitelist / local SDK snapshot / friendly name mapping) + **AdapterRegistry injection/get/fail-fast** + Env/Flag static fields + LLMConfig/ProviderConfig/ProviderAuthMethod zod schemas
+- `interfaces.test.ts` — V4-added: 5 AdapterRegistry interfaces + static reader functions (`readEnvString` / `readFlagBool` / `readFlagNumber`) + `lazyAsync()` reset behavior
+- `model-smoke.test.ts` — validates the type export path stability of `model/types.ts`
+- `setup.ts` — global test environment (sets NODE_ENV=development + **injects a complete mock AdapterRegistry** to prevent chain import triggering fail-fast)
+
+**All 75 tests currently green** (across 3 test files). Coverage breakdown:
+
+| Category | Case count | Validation |
+|----------|-----------|------------|
+| AdapterRegistry interfaces (V4 new) | 11 | 4 Provider interface contracts / `setAdapterRegistry` injection / `hasAdapterRegistry` boolean / fail-fast throw / static reader functions |
+| Provider constants | 11 | DEFAULT_ENABLED_PROVIDERS / CUSTOM_PROVIDER_DEFINITIONS / PROVIDER_DISPLAY_NAMES |
+| ProviderAuth lazyAsync behavior (V4 new) | 3 | `registerPluginAuthProvider` triggers `_state.reset()` / `clearPluginAuthProviders` resets cache / `ProviderAuth.resetState()` clears cache |
+| Model type export stability | 6 | RerankInput/Result/Response + Entity/Relation/GraphInput + Note/MemorySummary |
+| Env / Flag namespace static fields | 6 | Env mirrors process.env keys / Flag contains LLM-package internal flags / reader function signatures (empty string vs undefined) |
+| LLMConfig schema | 4 | Empty object passes / Complete fields pass / Invalid model rejected / Non-array enabled_providers rejected |
+| ProviderConfig schema | 3 | Minimal config passes / partial design (all fields optional) / options.apiKey type validation |
+| ProviderAuthMethod schema | 4 | api / oauth types pass / Invalid type rejected / Missing label rejected |
+
+**Full integration test boundary**: After the AdapterRegistry decoupling, the llm package can mock all 4 Providers independently, and a complete end-to-end flow of `Provider.list / getModel / parseModel` no longer depends on the agent package. Follow-up task: when the agent package switches LLM implementation, add cross-package integration tests (verifying that real injected Providers match the llm-package contract).
+
+## Development Commands
+
+```bash
+# Build (tsup, outputs ESM + CJS + DTS)
+pnpm --filter @easbot/llm build
+
+# Watch mode build
+pnpm --filter @easbot/llm dev
+
+# Regenerate models.dev snapshot (requires network)
+pnpm --filter @easbot/llm build:snapshot
+
+# Type check
+pnpm --filter @easbot/llm type-check
+
+# Lint (biome)
+pnpm --filter @easbot/llm lint
+
+# Lint fix
+pnpm --filter @easbot/llm lint:fix
+
+# Unit tests
+pnpm --filter @easbot/llm test:run
+```
+
+## Design Principles
+
+1. **Provider namespace is the only entry point**: business code should not directly import `@ai-sdk/openai` or other concrete SDKs — always go through `Provider.getModel('openai/gpt-4')`
+2. **Configuration vs injection separation**: `Config` (persistent config) and `Env/Auth/Plugin` (runtime injection) don't mix
+3. **Error normalization**: `ProviderError.parseAPICallError` unifies 25+ vendors' different error formats into `context_overflow | api_error` two-category
+4. **Local SDK priority over remote**: self-developed SDKs (ollama / easbot-local) don't appear on models.dev, so we use `CUSTOM_PROVIDER_DEFINITIONS` static injection to avoid remote catalog drift
+5. **Lazy SDK loading**: each provider's `BUNDLED_PROVIDERS[].loader()` is a `() => import('@ai-sdk/openai')` style dynamic import — business code that doesn't reference a provider doesn't download its SDK
+
+## Differences from Historical Versions
+
+| Version | Key Changes |
+|---------|-------------|
+| **Early placeholder (@easbot/types residue)** | Only a 5-line index.ts comment, no business capability |
+| **V3 (ADR 0070)** | Added `src/interfaces.ts` (6 Provider interfaces + AdapterRegistry) + `src/config/` three-file module; refactored provider/{auth,models,provider,transform}.ts to use AdapterRegistry throughout |
+| **V4 (ADR 0071)** | Removed `IInstanceProvider.state()` (decomposed to `@easbot/utils.lazyAsync()`) + removed `IPluginProvider` dependency (now module-level `_pluginAuthRegistry` + `ProviderAuth.registerPluginAuthProvider()` entry); Provider interfaces reduced from 6 to 5 |
+
+**V3 → V4 refactor motivation**:
+- `IInstanceProvider.state()` couples "per-process singleton + explicit reset" with the `Instance.directory` abstraction, but state caching has nothing to do with Instance paths
+- After decomposition to `@easbot/utils.lazyAsync()`, `IInstanceProvider` shrinks to 2 methods (`getDirectory` / `getWorktree`), with clean responsibility
+- `ProviderAuth` no longer depends on `IPluginProvider`, instead uses a module-level list + registration entry, with clearer semantics (plugin registration = push to list)
+
+See:
+- [ADR 0070 llm-adapter-registry](../../docs/decisions/0070-llm-adapter-registry.md) — AdapterRegistry injection pattern
+- [ADR 0071 llm-instance-state-decompose](../../docs/decisions/0071-llm-instance-state-decompose.md) — state decomposition