eggpool 0.4.1__tar.gz → 0.4.2__tar.gz

{eggpool-0.4.1 → eggpool-0.4.2}/AGENTS.md

@@ -76,6 +76,7 @@ CI sets `PYTHONHASHSEED=0` and `TZ=UTC`; reproduce locally for deterministic res
 - **Process model**: supervisor + Granian worker, PID file lifecycle, daemon mode. See `architecture/README.md` § Daemon Mode.
 - **Dashboard**: server-rendered HTML, 13 pages (including `/models/{model_id:path}` model-info detail), Chart.js v4, grouped timeseries, CSS tooltips. See `architecture` skill § Dashboard.
 - **Observability**: attempt analytics, routing analytics, latency phases, pending health, runtime metrics. See `architecture` skill § Runtime Observability.
+- **Catalog refresh semantics**: `CatalogService._fetch_and_process_account` returns an `AccountCatalogOutcome` enum (`SUCCESS_AUTHORITATIVE`, `SUCCESS_PARTIAL`, `SUCCESS_EMPTY`, `FAILED`, `SKIPPED`). Per-account cache updates run through `ModelCatalogCache.update_from_account(authoritative, allow_withdrawals)`, which is **non-destructive by default** — both flags default to `False`. The destructive `mark_account_models_unavailable` step is gated on `authoritative=True AND allow_withdrawals=True`, so the cache layer itself enforces the invariant. `ModelsConfig.catalog_withdrawal_policy` (`preserve_until_health` (default), `confirmed_once`, `confirmed_twice`) governs when the service flips `allow_withdrawals=True`. `SUCCESS_PARTIAL` always forces withdrawal off because a partial response is never a complete withdrawal confirmation. The per-cycle INFO summary at `_log_refresh_summary` reports per-outcome counts so operators can spot catalog uncertainty without enabling debug logging. See `architecture/README.md` § Catalog Refresh Semantics.
 - **Agent integrations**: `eggpool configsetup` generates configuration snippets for 11 coding agents (OpenCode, Claude Code, Aider, Codex, Qwen Code, Kilo, Continue, Cline, Roo Code, Goose, OpenHands). Target-specific generators live in `src/eggpool/integrations/`; shared utilities in `src/eggpool/config_utils.py` (`resolve_server_api_key`, `ServerKeyResolution`). Transcoder enablement is persisted to TOML when required. Secret output is controlled explicitly via `contains_secret`. See `architecture/README.md` § Package Structure.
 - **Model information**: `model_info/` sidecar subsystem with persistent metadata, provider-native observations (`ProviderCatalogSource`), OpenRouter metadata source (`OpenRouterModelInfoSource` — TTL-cached, exact alias matching, uses shared outbound client), identity resolution (`model_info/identity.py` — exact/curated alias matching only, no fuzzy matching), status classification, lifecycle wiring (`ModelInfoService`), background refresh scheduler (`ModelInfoRefreshScheduler`), catalog-refresh-driven reconciliation (`CatalogRefreshResult`), and CLI inspection. `ModelInfoSourceFetchError` for source failures. Phase 4 adds JSON API endpoints (`GET /api/model-info`, `GET /api/model-info/{model_id}`, `GET /api/model-info/sources`, `POST /api/model-info/refresh`), compact `/v1/models` enrichment under `eggpool.model_info`, and dashboard model-info status pills with tooltips. Phase 5 adds Artificial Analysis and Hugging Face source adapters, manual overrides (`[model_info.overrides]`), alias expansion (`[model_info.aliases]`), source health hardening (`rate_limited_until`, `last_status_code`, `last_payload_count`, `last_success_duration_ms`), richer summary generation (benchmarks, HF metadata, conflicts), and `model_info_overrides` table (migration `0037`). See `architecture/README.md` § Model Information.
 
@@ -85,6 +86,8 @@ CI sets `PYTHONHASHSEED=0` and `TZ=UTC`; reproduce locally for deterministic res
 - No pre-commit hooks are configured in this repo; CI runs ruff, pyright, and pytest via GitHub Actions
 - **`static_models` is the source of truth for provider-specific protocol** — `FAMILY_PROTOCOLS` (`src/eggpool/catalog/protocols.py`) is a global fallback. Providers like `minimax-cn` that serve MiniMax models on the OpenAI-compatible surface **must** ship `[[providers.<id>.static_models]]` rows with `protocol = "openai"`, otherwise the live `/v1/models` fetch resolves `MiniMax-M*` via the `minimax-` family prefix to `anthropic` and the protocol check clears it to `None`, producing `ModelUnavailableError` instead of `ProtocolMismatchError`. Static seeds survive via `ModelCatalogCache._preserve_static_fields` (`src/eggpool/catalog/cache.py:146-187`).
 - **Upstream-authoritative suppression**: local quota estimates are advisory by default (`local_quota_mode = "score_only"`). Only upstream-observed failures (429/402/5xx/auth) and explicit operator disablement suppress routing. Switch to `hard_cap` only as an opt-in escape hatch.
+- **Catalog non-destructive refresh**: `ModelCatalogCache.update_from_account(authoritative=False, allow_withdrawals=False)` (the default) preserves prior account/model support on every cycle — failed, empty, and partial refreshes never de-pool a healthy account. The destructive `mark_account_models_unavailable` step is only reached when the service explicitly sets both flags, gated by `ModelsConfig.catalog_withdrawal_policy`. Under the default `preserve_until_health` policy the flags are never flipped, so `HealthManager` is the only de-pooling mechanism. Static seeds (`_seed_static_models`) inherit the non-destructive default and survive future refresh cycles via `_preserve_static_fields`.
+- **Sibling-wins protocol guard**: `_provider_models` is keyed by `(model_id, provider_id)` and **shared** by every account that lists that provider (e.g. all `opencode-go-0001`/`-0002`/`-0003` accounts share one row per model on the `opencode-go` provider). `_preserve_resolved_protocol()` (`src/eggpool/catalog/cache.py`) is invoked on every non-destructive `update_from_account` call: when a per-provider row already has a resolved protocol and the new entry arrives with `protocol=None`, the prior protocol is preserved. This prevents a single sibling's partial refresh from silently de-pooling every account on that provider. The destructive path (`authoritative=True AND allow_withdrawals=True`) intentionally skips the guard.
 - **Same-tier fairness rotor**: EggPool is not purely lowest-score-wins for same-tier peer accounts. When accounts are effectively tied by priority, weight, health, protocol, and utilization score, same-tier fairness rotates candidates to avoid stable config-order bias and subscription starvation. When `fairness_mode = "round_robin"` (the default), effectively tied accounts within the same priority tier are rotated deterministically via `FairnessRotor` (`src/eggpool/routing/fairness.py`). Band membership requires same priority, same weight, same transcode status, and score within `fairness_epsilon` of the best. The server runtime honors all `[routing]` fairness config fields: `fairness_mode`, `fairness_epsilon`, and `fairness_scope`. The `fairness_scope` controls rotation group granularity: `provider_model_protocol` (default) includes the routed protocol in the key, `provider_model` intentionally collapses protocol groups, and `priority_model_protocol` intentionally co-balances same-priority providers serving the same model. The rotor's position map is capped at 4096 entries (`_ROTOR_HARD_CAP`); when reached the entire map is cleared and rotation restarts from 0. Restart also resets all rotor state — durable round-robin is explicitly out of scope.
 - **Backoff persistence**: upstream-derived backoffs survive restarts via the `account_backoffs` table (`src/eggpool/db/schema/0024_account_backoffs.sql`). Local cost overruns must never be persisted as backoff rows.
 - **Synthetic 503 vs 502**: `ModelUnavailableError` (503) is reserved for genuine pre-dispatch unavailability. `UpstreamExhaustedError` (502) is raised when every candidate account was attempted and exhausted mid-request.

{eggpool-0.4.1 → eggpool-0.4.2}/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Catalog non-destructive refresh contract.** `ModelCatalogCache.update_from_account()` now accepts `authoritative: bool = False, allow_withdrawals: bool = False`; both flags default to `False` so a failed, empty, or partial refresh cannot silently de-pool a healthy account. Operators opt into the old "refresh is the source of truth" behavior with `ModelsConfig.catalog_withdrawal_policy` (`preserve_until_health` default, `confirmed_once`, `confirmed_twice`). Under the default policy, health is the only de-pooling mechanism. `CatalogService._fetch_and_process_account()` returns an `AccountCatalogOutcome` enum (`SUCCESS_AUTHORITATIVE`, `SUCCESS_PARTIAL`, `SUCCESS_EMPTY`, `FAILED`, `SKIPPED`) plus an `AccountCatalogUpdateResult` summary row so the cache layer can stay non-destructive while operators still get full audit trail. `_log_refresh_summary` emits a single INFO line enumerating per-outcome counts after every cycle so catalog uncertainty shows up without enabling debug logging.
+- **`eggpool accounts explain --gates`** (`src/eggpool/cli_full.py`) renders the per-account gate breakdown (config, credentials, health, circuit, provider id registry/catalog match, provider-supports-protocol, model support row/availability/freshness, provider-metadata-exists, protocol_match, local_quota_gate, final_eligible) as a compact text table. Backed by `Router.explain_account_eligibility(include_gates=True)` and `Router._collect_gate_status(...)`; the breakdown is informational — the canonical decision still comes from `_classify_eligibility`.
 - **Same-tier account fairness rotor**: deterministic round-robin rotation for effectively tied same-tier accounts prevents routing starvation. Configurable via `[routing] fairness_mode`, `fairness_epsilon`, and `fairness_scope`. Defaults to `round_robin` with `provider_model_protocol` scope. Fairness decisions are recorded in `routing_decisions.score_components_json` under the `fairness` key for operator diagnostics. The `fairness` payload now includes the `scope` field, and each `top_candidates` entry carries `rank_before_fairness`, `rank_after_fairness`, and `fairness_band_member` for full traceability. The `FairnessRotor` position map is capped at 4096 entries (`_ROTOR_HARD_CAP`); when reached the entire map is cleared and rotation restarts from 0.
 - **Bidirectional OpenAI ↔ Anthropic protocol transcoding.** When `[transcoder] enabled = true`, requests from clients using one protocol can be forwarded to upstream accounts that speak only the other. Initial scope is text-only requests and responses, plus streaming SSE. Tool calls, vision, and extended thinking land in a follow-up release. See `docs/transcoding.md` for the full translation table.
 - New `eggpool stats transcoding [--period 1d|7d|30d]` subcommand for transcoding observability.
@@ -22,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - `RequestCoordinator` now carries `upstream_protocol` alongside `protocol` on `ProxyRequestContext`. Behaviour is identical when `[transcoder] enabled = false`.
+- **`ModelCatalogCache.update_from_account()` semantic shift — now non-destructive by default.** Both `authoritative` and `allow_withdrawals` keyword arguments default to `False`, so a per-account catalog update that omits previously-known support rows no longer silently de-pools those rows. Updates that already pass `authoritative=True, allow_withdrawals=True` continue to behave as before (and are still the only way to remove support via a refresh). All in-tree callers that intentionally destroy support — the destructive `prune_unused()` cleanup step and the explicit `update_from_account(...)` calls in `tests/unit/test_catalog.py` / `tests/integration/test_catalog_unresolved_models.py` — now pass both flags explicitly so the test suite continues to assert legacy destructive behavior. See `architecture/README.md` § Catalog Refresh Semantics.
 - **`RequestCoordinator._select_and_persist_attempt()` lock scope.** The runtime publication step (`Router.increment_active_request_count` + `QuotaEstimator.add_reservation`) now runs INSIDE `_select_lock` AFTER the durable transaction commits but BEFORE the lock releases. The two contexts are written as explicit nested `async with` blocks (outer `_select_lock`, inner `_db.transaction()`). Note: collapsing them back into the previous compound `async with self._select_lock, self._db.transaction():` form would NOT by itself re-introduce the stale-score race on context-exit-order grounds — Python exits context managers right-to-left, so the transaction would still commit before the lock released. The actual bug was that the runtime publication block lived INSIDE the transaction body, so active-count and reserved-cost state were published before the durable transaction committed. The explicit nested form makes it hard to accidentally place publication inside the transaction while still keeping publication under `_select_lock`. The key invariant is block placement (publication must be outside the DB transaction body but still inside `_select_lock`), not context-exit order. The compensation chain (decrement → finalize-as-cancelled → release health slot → set `client_metadata["post_commit_interrupted"]` → re-raise) is preserved and still catches `BaseException` (including `CancelledError` / `SystemExit` / `KeyboardInterrupt`, all re-raised without being swallowed).
 - `RoutingScore` gains diagnostic fields (`reserved_microdollars`, `cost_5h_microdollars`, `cost_7d_microdollars`, `cost_30d_microdollars`, `capacity_5h_microdollars`, `capacity_7d_microdollars`, `capacity_30d_microdollars`, `active_request_count`) so the scorer can return enough state to populate `score_components_json` without a second pass over the quota tables.
 - `RoutingDecisionTrace` gains `score_components: Mapping[str, Any] | None` plus `to_score_components_json()`; `RoutingDecisionRepository.create()` accepts an optional `score_components_json` argument (defaults to `'{}'` for backward compatibility with rows inserted by code paths that have not yet been migrated).
@@ -31,6 +34,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`eggpool accounts status` now prints `routing_priority`.** The per-line output gained a `priority=N` field derived from the account's provider, alongside `provider`, `enabled`, `weight`, and the api-key-env set state.
 - **`eggpool accounts explain` runs migrations on fresh installs.** The inner `_run_explain` coroutine now calls `MigrationRunner(db).run()` before hydrating `ModelCatalogCache.hydrate_from_db(db)`, so a brand-new (unmigrated) database path no longer crashes with `sqlite3.OperationalError: no such table: models` / `provider_model_metadata` / `account_models`. With no catalog rows yet, accounts surface a `no_model` verdict instead of the SQL error. The command still performs no outbound provider refresh.
 
+### Fixed
+
+- **Cross-account protocol poisoning from a partial sibling refresh.** `_provider_models` is keyed by `(model_id, provider_id)` and shared by every account that lists that provider (e.g. all `opencode-go-0001`/`-0002`/`-0003` accounts share one row per model on the `opencode-go` provider). Prior to this fix a single sibling's partial refresh — transient upstream parse error, unresolved family prefix, or a model whose protocol cannot be re-derived this cycle — produced a model entry with `protocol=None` and clobbered the previously-resolved protocol on the shared row, silently dropping every sibling account from routing even though `_account_support` still listed them. `ModelCatalogCache._preserve_resolved_protocol()` now applies a sibling-wins guard: a non-destructive `update_from_account` will keep the existing resolved protocol when the new entry's `protocol` is `None` and the prior row carried a resolved value. The destructive path (`authoritative=True AND allow_withdrawals=True`) intentionally skips the guard so operator-initiated withdrawals remain effective. `tests/unit/test_catalog_withdrawal_policy.py::test_partial_refresh_does_not_clobber_shared_provider_protocol{,multiple}` and `test_explicit_destructive_update_can_still_clear_protocol` pin the new contract.
+
 ## [0.3.5] - 2026-06-27
 
 ### Changed
@@ -43,6 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Exclusion taxonomy empty-state**: the Routing page's doughnut chart now shows `<p class="empty">No exclusion data in this period.</p>` instead of an invisible Chart.js ring when no exclusions have been recorded in the selected period. The previous behaviour rendered a zero-data doughnut whose legend was visible but the chart itself was not, producing a "key but no graph" artefact.
 - **`circuit_breaker` classification**: `SUPPRESSIVE_EXCLUSION_REASONS` now includes `circuit_breaker`, the only exclusion reason the coordinator actually writes to `exclude_reasons_json`. Previously every real-world exclusion landed in the `unknown` bucket because the frozenset only contained the legacy `circuit_open` name.
+- **Catalog empty-data list is now classified `SUCCESS_EMPTY`, not `SUCCESS_AUTHORITATIVE`.** `CatalogService._fetch_and_process_account()` now distinguishes between "no model list in the response payload" (the existing `SUCCESS_EMPTY` branch on `result.response == {}`) and "model list returned but zero normalizable items after filter" (a new branch that fires when `normalize_models(...) == []` with `result.error is None`). Prior to this fix a fully empty but healthy upstream response was reported as authoritative and could mask a regression in the upstream `/v1/models` payload; the per-cycle summary line in operators' logs now correctly enumerates these as `empty=N`.
 
 ### Added
 

{eggpool-0.4.1 → eggpool-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eggpool
-Version: 0.4.1
+Version: 0.4.2
 Summary: A lightweight proxy that aggregates multiple LLM provider accounts behind one OpenAI-compatible endpoint
 Project-URL: Homepage, https://github.com/eggstack/eggpool
 Project-URL: Repository, https://github.com/eggstack/eggpool
@@ -130,7 +130,7 @@ Use `eggpool connect` for interactive provider setup. See [docs/providers.md](do
 | `[server]` | Bind address, port (default 11300), API key, logging, threads |
 | `[upstream]` | Upstream API base URL, timeouts, connection pool |
 | `[database]` | SQLite path, WAL mode |
-| `[models]` | Catalog refresh, exposure mode, model collapse |
+| `[models]` | Catalog refresh, exposure mode, model collapse, withdrawal policy |
 | `[routing]` | Routing strategy, retry limits, quota mode, same-tier fairness |
 | `[dashboard]` | Dashboard toggle, theme, refresh interval |
 | `[providers.*]` | Provider configs with accounts and routing priority |
@@ -138,6 +138,8 @@ Use `eggpool connect` for interactive provider setup. See [docs/providers.md](do
 | `[model_info]` | Optional model metadata refresh, aliases, overrides, and external source settings |
 | `[transcoder]` | Protocol transcoding between OpenAI and Anthropic formats |
 
+The catalog refresh is **non-destructive by default**: failed, empty, or partial upstream responses never silently de-pool a healthy account. Set `[models].catalog_withdrawal_policy` (`preserve_until_health` default, `confirmed_once`, `confirmed_twice`) to opt into destructive behavior on authoritative refreshes. See `architecture/README.md` § Catalog Refresh Semantics.
+
 Full config reference: [`config.example.toml`](config.example.toml) | [docs/providers.md](docs/providers.md)
 
 ## Protocol transcoding
@@ -226,6 +228,8 @@ uv run pytest
 | OpenHands | `eggpool configsetup openhands` | Shell env exports | N/A (printed) | recommended | stable fragment |
 
 Shared options: `--host`, `--base-url`, `--model`, `--write`, `--output`, `--force`, `--no-clipboard`, `--print-secret`.
+Generated JSON, TOML, YAML, and shell snippets escape catalog/config values for
+the target format, including provider-suffixed model IDs.
 
 Examples:
 ```sh

{eggpool-0.4.1 → eggpool-0.4.2}/README.md

@@ -86,7 +86,7 @@ Use `eggpool connect` for interactive provider setup. See [docs/providers.md](do
 | `[server]` | Bind address, port (default 11300), API key, logging, threads |
 | `[upstream]` | Upstream API base URL, timeouts, connection pool |
 | `[database]` | SQLite path, WAL mode |
-| `[models]` | Catalog refresh, exposure mode, model collapse |
+| `[models]` | Catalog refresh, exposure mode, model collapse, withdrawal policy |
 | `[routing]` | Routing strategy, retry limits, quota mode, same-tier fairness |
 | `[dashboard]` | Dashboard toggle, theme, refresh interval |
 | `[providers.*]` | Provider configs with accounts and routing priority |
@@ -94,6 +94,8 @@ Use `eggpool connect` for interactive provider setup. See [docs/providers.md](do
 | `[model_info]` | Optional model metadata refresh, aliases, overrides, and external source settings |
 | `[transcoder]` | Protocol transcoding between OpenAI and Anthropic formats |
 
+The catalog refresh is **non-destructive by default**: failed, empty, or partial upstream responses never silently de-pool a healthy account. Set `[models].catalog_withdrawal_policy` (`preserve_until_health` default, `confirmed_once`, `confirmed_twice`) to opt into destructive behavior on authoritative refreshes. See `architecture/README.md` § Catalog Refresh Semantics.
+
 Full config reference: [`config.example.toml`](config.example.toml) | [docs/providers.md](docs/providers.md)
 
 ## Protocol transcoding
@@ -182,6 +184,8 @@ uv run pytest
 | OpenHands | `eggpool configsetup openhands` | Shell env exports | N/A (printed) | recommended | stable fragment |
 
 Shared options: `--host`, `--base-url`, `--model`, `--write`, `--output`, `--force`, `--no-clipboard`, `--print-secret`.
+Generated JSON, TOML, YAML, and shell snippets escape catalog/config values for
+the target format, including provider-suffixed model IDs.
 
 Examples:
 ```sh

{eggpool-0.4.1 → eggpool-0.4.2}/architecture/README.md

@@ -43,6 +43,11 @@ src/eggpool/
 └── constants.py       # Project-wide constants
 ```
 
+`integrations/common.py` owns configsetup context construction, catalog-backed
+default model resolution, and format-safe scalar/key rendering helpers. New
+agent targets should reuse those helpers instead of hand-quoting JSON, TOML,
+YAML, shell, or model ID values in target modules.
+
 ## Request Lifecycle
 
 All data-plane requests flow through `RequestCoordinator`:
@@ -507,6 +512,95 @@ suffixed (or unsuffixed) model ID.
   provider block and leaves existing blocks untouched, so operators can edit
   one number to rebalance.
 
+## Catalog Refresh Semantics
+
+The catalog refresh path is **non-destructive by default**. Healthy
+account/model support rows survive every refresh cycle so a transient
+network blip, an empty upstream response, or a partially-normalized
+response cannot silently de-pool a healthy account. The only de-pooling
+mechanism in the catalog layer is `HealthManager`; configuration and
+health state jointly own the eligibility decision.
+
+### Per-account outcome classification
+
+`CatalogService._fetch_and_process_account` categorizes every refresh
+attempt and returns an `AccountCatalogOutcome` plus, on success, an
+`AccountCatalogUpdateResult`:
+
+| Outcome | When | Cache touched? |
+| ------- | ---- | -------------- |
+| `SUCCESS_AUTHORITATIVE` | HTTP 2xx, fully protocol-resolved, non-empty | Add/update only unless `catalog_withdrawal_policy` permits withdrawal |
+| `SUCCESS_PARTIAL` | HTTP 2xx, but at least one model lacks a resolved protocol | Add/update only; withdrawal forced off |
+| `SUCCESS_EMPTY` | HTTP 2xx with zero normalizable models | No-op (prior support preserved) |
+| `FAILED` | Network/5xx/auth/quota/JSON-shape failure | **No** (cache untouched) |
+| `SKIPPED` | Fetcher returned without contacting upstream | **No** (cache untouched) |
+
+### Withdrawal policy
+
+`ModelsConfig.catalog_withdrawal_policy` controls when withdrawal is
+permitted:
+
+- `preserve_until_health` (default) — withdrawal is **never**
+  triggered by a refresh. Health state is the sole de-pooling
+  mechanism.
+- `confirmed_once` — a single authoritative refresh may withdraw
+  support for models no longer advertised.
+- `confirmed_twice` — two consecutive authoritative refreshes are
+  required to withdraw support.
+
+`SUCCESS_PARTIAL` overrides the policy for that cycle and forces
+`allow_withdrawals = False` because a partial response is never a
+complete withdrawal confirmation. The destructive
+`mark_account_models_unavailable` step is also gated on
+`authoritative=True, allow_withdrawals=True` so the cache layer
+itself enforces the invariant; the service decides which flags to
+flip based on outcome category and policy.
+
+### Per-cycle operational logging
+
+`CatalogService.refresh()` calls `_log_refresh_summary` after every
+cycle. The INFO log enumerates per-outcome counts on one line so
+operators can spot catalog uncertainty without enabling debug
+logging:
+
+```
+Catalog refresh summary: policy=preserve_until_health total=3 authoritative=1 partial=0 empty=1 failed=1 skipped=0
+```
+
+A run with many `FAILED` or `PARTIAL` rows is signal that an upstream
+or DNS path is unhealthy; a sudden shift in `AUTHORITATIVE` count
+indicates a real catalog change that may need rebalancing.
+
+### Gate diagnostics for `accounts explain`
+
+`Router.explain_account_eligibility(include_gates=True)` returns a
+per-account gate breakdown dict (config, credentials, health,
+circuit, provider, protocol, model support, freshness, provider
+metadata, protocol match, local quota, final eligible) so operators
+can pinpoint exactly which gate is failing without running live
+traffic. The dict is informational; the canonical decision still
+comes from `_classify_eligibility`. The `eggpool accounts explain
+--gates` CLI command renders the same breakdown as a compact
+text table.
+
+### Shared per-provider metadata and sibling-wins protocol guard
+
+`_provider_models` is keyed by `(model_id, provider_id)` and is
+**shared** by every account that lists that provider — e.g. all
+`opencode-go-0001`/`-0002`/`-0003` accounts share one row per
+model on the `opencode-go` provider. The previous
+`update_from_account()` clobbered this shared dict unconditionally
+even on partial responses, which produced the upstream-reported
+"all traffic on `opencode-go-0001`, none on `0002`/`0003`" regression
+when a single account's refresh resolved the protocol as `None`.
+`_preserve_resolved_protocol()` now applies a sibling-wins guard
+in the non-destructive path: when a per-provider row already has a
+resolved protocol and the new entry arrives with `protocol=None`,
+the prior protocol is preserved and the resulting per-provider row
+is shared across all sibling accounts. The destructive path
+(`authoritative=True AND allow_withdrawals=True`) intentionally
+skips the guard so operator-initiated withdrawals remain effective.
+
 ## Error Hierarchy
 
 ```

{eggpool-0.4.1 → eggpool-0.4.2}/config.example.toml

@@ -38,6 +38,18 @@ ping_retain_days = 7
 #                          # providers is collapsed to a single unsuffixed
 #                          # ID and routed across all of them. Default false
 #                          # emits one provider-suffixed entry per provider.
+# Catalog withdrawal policy controls whether a live refresh can remove
+# an account/model support row that the cache previously knew about.
+# Default "preserve_until_health" never de-pools on catalog uncertainty:
+# only explicit health/config state (auth failure, quota exhaustion,
+# rate-limit, cooldown, circuit open, account disabled) suppresses
+# routing. "confirmed_once" allows a successful authoritative non-empty
+# refresh that omits a model to remove that account/model support.
+# "confirmed_twice" requires two consecutive authoritative omissions.
+# Default is correct for subscription aggregation: a flaky /models
+# response or transient upstream parse error must not silently de-pool
+# a healthy subscription account.
+catalog_withdrawal_policy = "preserve_until_health"
 
 # ─── Protocol Transcoding ────────────────────────────────────────────
 # Transcoding is **on by default**. Requests from clients using one

{eggpool-0.4.1 → eggpool-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eggpool"
-version = "0.4.1"
+version = "0.4.2"
 description = "A lightweight proxy that aggregates multiple LLM provider accounts behind one OpenAI-compatible endpoint"
 readme = "README.md"
 requires-python = ">=3.11"

{eggpool-0.4.1 → eggpool-0.4.2}/src/eggpool/_share/config.example.toml

@@ -40,6 +40,18 @@ stale_after_s = 7200
 allow_stale_catalog = true
 # How many days to retain provider ping data.
 ping_retain_days = 7
+# Catalog withdrawal policy controls whether a live refresh can remove
+# an account/model support row that the cache previously knew about.
+# Default "preserve_until_health" never de-pools on catalog uncertainty:
+# only explicit health/config state (auth failure, quota exhaustion,
+# rate-limit, cooldown, circuit open, account disabled) suppresses
+# routing. "confirmed_once" allows a successful authoritative non-empty
+# refresh that omits a model to remove that account/model support.
+# "confirmed_twice" requires two consecutive authoritative omissions.
+# Default is correct for subscription aggregation: a flaky /models
+# response or transient upstream parse error must not silently de-pool
+# a healthy subscription account.
+catalog_withdrawal_policy = "preserve_until_health"
 
 [routing]
 strategy = "quota_fair"

{eggpool-0.4.1 → eggpool-0.4.2}/src/eggpool/app.py

@@ -735,6 +735,15 @@ async def _lifespan_runtime(app: FastAPI) -> AsyncGenerator[None]:
                     )
                 except Exception:
                     logger.exception("Model info startup reconciliation failed")
+                # Backfill canonical rows for any models table rows
+                # that reconcile_catalog_snapshot missed (e.g. models
+                # withdrawn and later reappeared).
+                try:
+                    backfill = await model_info.backfill_missing_canonical()
+                    if backfill["backfilled"] > 0:
+                        logger.info("Model info startup backfill: %s", backfill)
+                except Exception:
+                    logger.exception("Model info startup backfill failed")
         except Exception:
             logger.exception("Failed to initialize model info service")
             model_info = None
@@ -959,6 +968,15 @@ async def _lifespan_runtime(app: FastAPI) -> AsyncGenerator[None]:
             lambda: model_info.run_periodic_refresh(),
         )
 
+    # Register periodic backfill of canonical rows for models that lack
+    # one.  Runs every 60s so withdrawn-and-reappeared models are
+    # covered within one cycle.
+    if config.model_info.enabled and model_info is not None:
+        supervisor.register(
+            "model_info_canonical_backfill",
+            lambda: model_info.run_backfill_missing_canonical(),
+        )
+
     # Register retention cleanup task (runs every hour)
     async def _retention_cleanup() -> None:
         while True:

{eggpool-0.4.1 → eggpool-0.4.2}/src/eggpool/catalog/cache.py

@@ -6,6 +6,8 @@ import datetime as _dt
 import json
 import logging
 import time
+from dataclasses import dataclass
+from enum import Enum
 from typing import TYPE_CHECKING, Any, cast
 
 from eggpool.catalog.limits import EffectiveModelLimits, conservative_limits
@@ -21,6 +23,41 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+class AccountCatalogOutcome(Enum):
+    """Result of a per-account catalog fetch.
+
+    The catalog service categorizes each refresh response before touching
+    the in-memory cache so that failed, empty, or partial refreshes do not
+    silently de-pool a healthy account. Only ``SUCCESS_AUTHORITATIVE``
+    responses are allowed to remove support from the cache.
+    """
+
+    SUCCESS_AUTHORITATIVE = "success_authoritative"
+    SUCCESS_EMPTY = "success_empty"
+    SUCCESS_PARTIAL = "success_partial"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True, slots=True)
+class AccountCatalogUpdateResult:
+    """Summary of a single ``update_from_account`` call.
+
+    Surfaced to the catalog service so it can record an operational
+    event and so a destructive update can be audited (which models
+    were added, updated, withdrawn, or preserved).
+    """
+
+    account_name: str
+    provider_id: str
+    authoritative: bool
+    allow_withdrawals: bool
+    added_support: int
+    updated_support: int
+    preserved_support: int
+    withdrawn_support: int
+
+
 def parse_model_id(
     model_id: str, known_providers: set[str] | None = None
 ) -> tuple[str, str | None]:
@@ -137,26 +174,77 @@ class ModelCatalogCache:
         account_name: str,
         provider_id: str,
         models: list[dict[str, Any]],
-    ) -> None:
-        """Update cache with models from a specific account."""
+        *,
+        authoritative: bool = False,
+        allow_withdrawals: bool = False,
+    ) -> AccountCatalogUpdateResult:
+        """Update cache with models from a specific account.
+
+        ``authoritative`` and ``allow_withdrawals`` gate the destructive
+        path so a failed, empty, or partial refresh cannot silently
+        de-pool a healthy account. Live fetch callers should pass
+        ``authoritative=True`` only after a successful non-empty
+        response that has been protocol-resolved, and
+        ``allow_withdrawals=True`` only when the configured
+        ``catalog_withdrawal_policy`` permits it (default: never).
+
+        Semantics:
+
+        - The ``account_name -> provider_id`` mapping is always set.
+        - The supplied ``models`` are always added or updated; the
+          in-memory cache learns about new model/account support
+          regardless of the outcome category.
+        - When ``authoritative and allow_withdrawals`` are both true,
+          any account/model support the new response omits is removed
+          (the legacy "refresh is the source of truth" behavior).
+        - Otherwise prior support is preserved; the destructive
+          ``mark_account_models_unavailable`` step is skipped.
+
+        Returns an :class:`AccountCatalogUpdateResult` summarizing the
+        counts of added, updated, preserved, and withdrawn support
+        rows. The result is informational — the service layer uses it
+        to log/emit operational events.
+        """
         self._account_providers[account_name] = provider_id
         now = time.time()
-        # A refresh response is authoritative for this account. Clear
-        # prior support first so models withdrawn upstream stop being
-        # exposed or routed for this account while other accounts'
-        # support remains intact.
-        self.mark_account_models_unavailable(account_name)
+        added = 0
+        updated = 0
+        preserved = 0
+        withdrawn = 0
+
+        # Destructive withdrawal path is only taken when both flags are
+        # set. Default behavior is non-destructive: catalog uncertainty
+        # must not silently de-pool a healthy account.
+        withdraw_destructive = authoritative and allow_withdrawals
+        if withdraw_destructive:
+            # Count the support rows the destructive step is about to
+            # remove so the result object carries the number of rows
+            # actually withdrawn, not just whether one was requested.
+            for accounts in self._account_support.values():
+                if account_name in accounts:
+                    withdrawn += 1
+            self.mark_account_models_unavailable(account_name)
+        else:
+            # Tally preserved support for the result object before any
+            # additions below so the count reflects the snapshot of
+            # what the cache knew about this account.
+            for accounts in self._account_support.values():
+                if account_name in accounts:
+                    preserved += 1
 
         # Drop any per-provider rows this account used to advertise
         # but the new response no longer includes.  A row survives when
         # at least one other account on the same provider still
         # publishes it; otherwise it is removed so the in-memory cache
-        # converges with the live catalog.
+        # converges with the live catalog.  This step only runs in the
+        # destructive path — in the non-destructive path, missing
+        # (model_id, provider_id) rows survive because the prior
+        # account may simply have failed to refresh this cycle.
         new_keys: set[tuple[str, str]] = set()
         for model in models:
             new_keys.add((model["model_id"], provider_id))
         prior_keys = self._account_provider_keys.get(account_name, set())
-        if prior_keys - new_keys:
+        if withdraw_destructive and prior_keys - new_keys:
             surviving: set[tuple[str, str]] = set()
             for other_acct, other_keys in self._account_provider_keys.items():
                 if other_acct == account_name:
@@ -186,6 +274,8 @@ class ModelCatalogCache:
                 "effective_limits": model.get("effective_limits", {}),
             }
             self._preserve_static_fields(provider_key, model_info)
+            if not withdraw_destructive:
+                self._preserve_resolved_protocol(provider_key, model_info)
 
             # Global entry: only materialize a global row if this
             # provider brings new information that the existing global
@@ -212,10 +302,24 @@ class ModelCatalogCache:
                 global_info["last_seen_at"] = now
 
             existing_support = self._account_support.get(model_id, frozenset())
+            if account_name in existing_support:
+                updated += 1
+            else:
+                added += 1
             self._account_support[model_id] = existing_support | {account_name}
 
         self._last_refresh = now
         self._account_last_refresh[account_name] = now
+        return AccountCatalogUpdateResult(
+            account_name=account_name,
+            provider_id=provider_id,
+            authoritative=authoritative,
+            allow_withdrawals=allow_withdrawals,
+            added_support=added,
+            updated_support=updated,
+            preserved_support=preserved,
+            withdrawn_support=withdrawn,
+        )
 
     @staticmethod
     def _effective_limits_from_info(
@@ -247,9 +351,9 @@ class ModelCatalogCache:
 
         When a live row arrives for a model that already has a
         ``static_config``-sourced provider entry, explicit static
-        protocol and capability fields win over a live row that did not
-        bring its own resolution. The merge mutates *model_info* in
-        place so callers can write the merged value into the cache.
+        protocol and capability fields win over a live row that did
+        not bring its own resolution. The merge mutates *model_info*
+        in place so callers can write the merged value into the cache.
         """
         existing = self._provider_models.get(provider_key)
         if existing is None:
@@ -281,6 +385,42 @@ class ModelCatalogCache:
             new_caps["supports_vision"] = existing_caps["supports_vision"]
         model_info["capabilities"] = new_caps
 
+    def _preserve_resolved_protocol(
+        self,
+        provider_key: tuple[str, str],
+        model_info: dict[str, Any],
+    ) -> None:
+        """Sibling-wins guard: never let a partial live update downgrade a
+        previously-resolved per-provider protocol to ``None``.
+
+        ``_provider_models`` is keyed by ``(model_id, provider_id)`` and
+        is shared by every account that lists that provider — e.g. all
+        three ``opencode-go-000X`` accounts share one row per model on
+        the ``opencode-go`` provider. When one account has a partial
+        refresh (transient upstream parse error, unresolved family
+        prefix, or a model whose protocol cannot be re-derived this
+        cycle), its ``model["protocol"]`` arrives as ``None``. Without
+        this guard, that single partial row would clobber the prior
+        resolved value for every sibling account, silently de-pooling
+        all of them from routing. The destructive ``update_from_account``
+        path (``authoritative=True and allow_withdrawals=True``)
+        intentionally skips this guard so an operator-initiated
+        withdrawal can still take effect.
+        """
+        existing = self._provider_models.get(provider_key)
+        if existing is None:
+            return
+        new_protocol = model_info.get("protocol")
+        new_protocol_source = model_info.get("protocol_source")
+        if new_protocol:
+            return
+        if not existing.get("protocol"):
+            return
+        if new_protocol_source in {"config", "static_config"}:
+            return
+        model_info["protocol"] = existing.get("protocol")
+        model_info["protocol_source"] = existing.get("protocol_source")
+
     def _visible_provider_ids(
         self,
         visible_accounts: AbstractSet[str],