dsh-model-pool 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-03
+
+First public release. `dsh-model-pool` aggregates every registered provider's models into
+one model pool: you pick a pooled model once and a configurable strategy routes each call to
+a concrete provider, with failover, thinking-depth selection and unavailable-route markers.
+
+### Added
+
+- One virtual provider route (`model-pool`) built from the union of every registered
+  provider's models, grouped by normalized model name, so pooled models appear in the
+  ordinary composer picker with their thinking-depth menus.
+- Six routing strategies: `priority`, `round-robin`, `weighted-random`, `least-used`,
+  `fastest` (EWMA of time-to-first-chunk) and `cheapest`. All are stable, with the provider
+  priority order as the common tie-break.
+- Sticky sessions (on by default): a conversation keeps the route that served its first
+  call, failover moves the pin to the route that actually answered, a different pooled model
+  starts fresh, and conversations that never select the pool are untouched.
+- Peak / idle provider ranking (`peakProviderOrder`, `offPeakProviderOrder`) as an overlay
+  on `providerOrder`: the six strategy ids are unchanged, and a policy with no ranking
+  configured is inert.
+- A fetched Chinese statutory holiday calendar (`holiday-cn`), cached at
+  `$DSH_HOME/model-pool/calendar.json` and refreshed in the background. No date is ever
+  entered by hand, and the network can never break routing: a failed fetch keeps the cache,
+  and before the first successful sync the plain weekday rule applies.
+- Live period reporting in Settings and over `/api/model-pool/state`: the current peak/idle
+  period, the local date and time, the configured windows, and when the period next flips.
+- Thinking-depth union across a pool's candidates, mapped to the nearest tier the target
+  route actually supports instead of failing with `UNSUPPORTED_REASONING_EFFORT`, plus the
+  minimum context window across candidates.
+- Input-modality union with per-call narrowing: an image-carrying call is filtered to
+  image-capable routes before the strategy, cooldown and sticky layers run, so the pool's
+  advertised image support is honoured rather than merely declared.
+- Per-route health registry with `ok` / `degraded` / `unavailable` / `unknown` states,
+  failure codes and a cooldown window. Failover happens only while no content has reached
+  the consumer; `maxAttempts` bounds the candidates tried, and `fallback: false` turns the
+  pool back into a single route.
+- Settings → Model Pool page: strategy selector, behaviour switches, peak/idle card with the
+  live period and calendar sync status, provider-priority editor, merged-group editor,
+  per-model rows with aggregate and per-route states, refresh and reset-health buttons.
+- Composer dock badge showing the live route of the current session — provider, concrete
+  model id, thinking depth and pool model — settled before the terminal chunk and excluding
+  session-title and compaction calls.
+- `modelGroups`: merge the same logical model across provider-specific ids, with
+  concrete-id, `provider/model` and glob selectors matched first-come. `merge: true` claims
+  routes away from their single-id rows; `merge: false` adds a curated pool alongside them.
+  Two groups ship by default (`DeepSeek V4.1 Flash`, `GLM 5.3 Flash`).
+- Bilingual UI locale (`en` / `zh`) and plugin icon.
+- HTTP state API under `/api/model-pool`: `state`, `session`, `refresh`,
+  `reset-health` and `refresh-calendar`.
+- A dependency-free `node --test` suite (316 tests) covering grouping, strategies, health,
+  effort mapping, input capabilities, peak periods and the holiday calendar.
+
+### Documented
+
+- README with install paths, usage, strategy semantics, the full configuration reference and
+  the mechanism behind the pool.
+- [`docs/CONTRACT.md`](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/docs/CONTRACT.md)
+  — verified Host API evidence and the module contract the code is written against.
+- [`docs/installation.md`](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/docs/installation.md) — install, verify and troubleshooting
+  guide.
+- [`docs/releasing.md`](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/docs/releasing.md)
+  — tag-driven release process and the one-time `NPM_TOKEN` setup.
+- Simplified Chinese translations of the README and both guides.
+
+[Unreleased]: https://github.com/BruceZhang1993/dsh-model-pool/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/BruceZhang1993/dsh-model-pool/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruce Zhang
+
+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.md

@@ -1,3 +1,509 @@
-# Temporary Holding Version
+# dsh-model-pool
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/BruceZhang1993/dsh-model-pool/actions/workflows/ci.yml/badge.svg)](https://github.com/BruceZhang1993/dsh-model-pool/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/dsh-model-pool.svg)](https://www.npmjs.com/package/dsh-model-pool)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-model-pool.svg)](https://www.npmjs.com/package/dsh-model-pool)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/LICENSE)
+![Node.js >= 20](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)
+[![DeepSeek Harness plugin](https://img.shields.io/badge/DeepSeek_Harness-plugin-4d6bfe.svg)](https://github.com/deepseek-ai/deepseek-harness)
+
+[**English**](README.md) · [简体中文](README.zh-CN.md)
+
+A DeepSeek Harness plugin that turns **every registered provider into one model pool**.
+
+You pick a model *once* — the pool decides which concrete provider serves each call,
+according to a strategy you choose. If a provider is down, the pool skips it, fails over
+to the next candidate, and marks it unavailable in the UI until it recovers.
+
+```
+composer picker                     model pool                       concrete providers
+─────────────────                   ──────────                       ──────────────────
+  Model Pool
+    DeepSeek V4 Pro   ──────►   strategy + health gate   ──────►   deepseek-account / deepseek-v4-pro
+    DeepSeek Flash               (priority, round-robin,             workbuddy / deepseek-v4-pro
+    GLM 5.3 Flash                 least-used, fastest, …)            workbuddy-global / …
+    …
+  thinking depth: high ─────►   mapped to each target's nearest tier
+```
+
+## Why
+
+Providers overlap. `deepseek-v4-pro` may be served by the first-party account *and* by a
+third-party route; `deepseek-v4.1-flash` may exist on several. Today you must pick one
+route per session and remember which one is healthy. This plugin makes the *model* the
+unit of choice and the *provider* an implementation detail.
+
+## Install
+
+**Requirements:** DeepSeek Harness Desktop or CLI, Node.js **>= 20**. No build step and no
+runtime dependencies — the Host half is plain ESM, the browser half is a hand-written
+`window.__ModuleLoader__` module that only `require('react')`s. The two peer dependencies
+(`@deepseek-ai/dsh-llm`, `@deepseek-ai/schemastery`) are provided by the Host, so nothing
+has to be installed alongside the plugin.
+
+### DSH Desktop
+
+Open the **plugin manager**, search the registry for `dsh-model-pool`, and install it.
+Restart DSH Desktop afterwards.
+
+### CLI profiles
+
+```sh
+dsh plugin --profile web add dsh-model-pool          # latest
+dsh plugin --profile web add dsh-model-pool@0.1.0    # pin a version
+```
+
+`dsh plugin` delegates to pnpm inside the profile directory and selects the bundle in
+`dsh.profile.bundles`. Restart the profile afterwards.
+
+### Local checkout
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-model-pool
+```
+
+That is the development install: pnpm links the checkout instead of downloading it, so the
+next restart picks up your edits.
+
+### Verify
+
+- **Settings → Model Pool** exists, and lists every pooled model with its provider count,
+  thinking depths and per-route state badges.
+- The composer model picker contains a **Model Pool** entry; pick one of its models and each
+  call is routed through the pool.
+
+Both halves ship in the same package: `dsh.bundle.patch` is the Host half (`index.js` +
+`lib/`) and `dsh.client` is the browser half (`client.js`). Nothing is built at install
+time.
+
+The full guide, including troubleshooting, is in [`docs/installation.md`](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/docs/installation.md).
+
+## Use
+
+1. Open **Settings → Model Pool**. It lists every pooled model, how many providers serve
+   it, its thinking depths, and a per-route state badge.
+2. Choose a **strategy** (below) and the behaviour switches. Optionally give the peak and
+   the idle period their own provider ranking in the **峰谷时段（peak / idle）** card, which
+   also shows the live period, when it next flips, and the statutory holiday calendar that
+   the plugin keeps in sync by itself — there is nothing to fill in by hand.
+3. In the composer model picker, pick a **Model Pool** model and a thinking depth.
+4. Each call is routed; failures cool a route down and fail over to the next candidate.
+
+## Strategies
+
+| Strategy | What it does | When to use |
+|---|---|---|
+| `priority` | Try providers in the configured priority order. | A clear first choice (e.g. first-party) with a backup. |
+| `round-robin` | Rotate the starting provider on every call. | Spread load evenly across equivalent routes. |
+| `weighted-random` | Draw at random, honouring each provider's weight. | Keep traffic mostly on a preferred route without hard pinning. |
+| `least-used` | Prefer the provider that has served the fewest calls. | Balance without a strict rotation. |
+| `fastest` | Prefer the lowest recent time-to-first-chunk. | Latency-sensitive work; adapts as providers slow down. |
+| `cheapest` | Prefer the lowest declared cost hint. | Cost-sensitive bulk work. |
+
+`priority`, `least-used`, `fastest` and `cheapest` are stable: equal keys keep the
+priority order, so routing never becomes unpredictable. `fastest` learns from real calls
+(an EWMA of time-to-first-chunk), so the first call on each route is a probe.
+
+### Keeping one conversation on one route
+
+`sticky` (on by default) pins a conversation to the route that served its first call:
+
+| | Without sticky | With sticky |
+|---|---|---|
+| `round-robin`, four turns in one chat | `A B C A` | `A A A A` |
+| A second chat | continues the rotation | picks its own route, then stays |
+
+The point is the provider's prompt cache: re-deciding every turn throws away the cached
+prefix, so a long conversation gets slower and more expensive than it needs to be. With
+sticky on, switching providers happens once per conversation instead of once per message.
+
+It is a preference, not a lock:
+
+- **Failover still works.** If the pinned route fails before producing output, the call
+  moves to the next candidate, and the *survivor* becomes the new pin.
+- **Unhealthy routes are skipped.** A pin inside its cooldown stops matching, so the
+  strategy decides again.
+- **A different pooled model starts fresh.** Re-selecting the pool with another model does
+  not inherit the previous model's provider.
+- **Only pooled calls participate.** A conversation that never selects the pool is
+  untouched.
+
+Turn it off in **Settings → Model Pool → Behaviour** when you want per-call spreading
+(quota sharing across accounts) rather than cache reuse.
+
+### Setting the provider priority
+
+The `priority` strategy ranks providers by `providerOrder` — a list of provider ids from
+highest to lowest. **Settings → Model Pool → Provider priority** lists every registered
+provider by its display name; reorder with the arrow buttons and save. You never type an
+id there. Only providers that currently contribute a model to the pool are listed — a
+provider with no models cannot be routed to, so ranking it would change nothing. The same ranking can be set in `cordis.patch.yml`:
+
+```yaml
+providerOrder: [deepseek-account, workbuddy, our-free-model]
+```
+
+With nothing configured the list shows plain registration order, which is exactly what the
+router falls back to. Providers you leave out follow the listed ones in registration order,
+so a partial list is valid — move just your first choice up and everything else stays
+behind it. Saving the untouched registration order stores an empty ranking rather than a
+redundant full list. A provider that is registered but currently serves no models still
+appears, because it is registered; one that has disappeared is kept and flagged rather
+than dropped silently.
+
+The same list also decides the tie-break for `least-used`, `fastest` and `cheapest`, and
+the fallback order after a failover.
+
+### 峰谷时段（peak / idle）
+
+Providers are not equally attractive at every hour. A first-party account may be cheap and
+fast outside business hours but rationed during them; a paid backup is often the reverse. So
+the pool can rank providers differently depending on whether the current moment is **peak**
+or **idle**.
+
+The shipped default is a Chinese business-hours policy:
+
+| Aspect | Default |
+|---|---|
+| Time zone | `Asia/Shanghai` (北京时间) |
+| Peak days | Monday–Friday |
+| Peak windows | `09:00-12:00` and `14:00-18:00` |
+| Peak exceptions | official 调休上班日 — a make-up Saturday is a working day |
+| Everything else | **idle** — weekends all day, statutory holidays all day, plus the lunch break, evenings and nights |
+
+A Beijing Friday 19:00, any ordinary Saturday and the whole National Day week are all idle; the
+Saturday the State Council opens to make up for a holiday is not.
+
+Two lists carry the rankings, and they obey the same rules as `providerOrder`: highest
+first, a partial list is valid, and an empty list means *this period has no opinion* — it
+inherits `providerOrder` rather than clearing the ranking. That is what keeps the feature
+inert until you configure it: with both lists empty, routing is exactly what it was before.
+
+```yaml
+peakProviderOrder: [workbuddy]            # ranking while peak; empty = inherit providerOrder
+offPeakProviderOrder: [deepseek-account]  # ranking while idle; empty = inherit providerOrder
+```
+
+Set them in **Settings → Model Pool → 峰谷时段（peak / idle）**, which offers the same
+arrow-button editor as the provider priority, or in `cordis.patch.yml`. Because the overlay
+reorders the candidates *before* the strategy runs, `priority` follows it directly and
+`least-used`, `fastest` and `cheapest` inherit it as their tie-break — the same way
+`providerOrder` already works. `round-robin` rotates through the period order, and
+`weighted-random` still draws by weight, using that order only to settle equal-weight and
+zero-weight routes.
+
+The day itself is configurable too:
+
+```yaml
+peakTimeZone: Asia/Shanghai
+peakWindows: ['09:00-12:00', '14:00-18:00']   # 'HH:MM-HH:MM'; 24:00 is a valid end
+peakWeekdays: [1, 2, 3, 4, 5]                 # ISO: 1 = Monday … 7 = Sunday
+peakMakeupWorkdays: []                        # extra 调休上班日 on top of the fetched ones
+```
+
+There is deliberately **no holiday list here**. 法定节假日 and 调休上班日 are fetched from a
+maintained dataset and kept up to date by the plugin, so nobody types dates and nothing goes
+stale when the State Council publishes next year's arrangement — see below.
+
+#### 法定节假日自动同步
+
+A worked Chinese calendar cannot be derived from a rule: 调休 moves days around every year.
+The plugin therefore reads it as data, from
+[`holiday-cn`](https://github.com/NateScarlet/holiday-cn) (NateScarlet, MIT) — one JSON
+document per year, generated from the State Council notice and carrying that notice's URL in
+its `papers` field. That is a real dependency worth knowing about: this plugin ships no
+holiday table of its own.
+
+```jsonc
+{ "year": 2026,
+  "papers": ["https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm"],
+  "days": [ { "name": "元旦", "date": "2026-01-01", "isOffDay": true },   // 法定节假日
+            { "name": "元旦", "date": "2026-01-04", "isOffDay": false } ] } // 调休上班日
+```
+
+The document is fetched from jsDelivr, falling back to `raw.githubusercontent.com` when the
+CDN is unreachable, and cached at `$DSH_HOME/model-pool/calendar.json` (under `~/.dsh` when
+`DSH_HOME` is unset). A background refresh runs every `holidayUpdateDays` (7), and re-fetches
+only when the cache is older than `holidayCacheDays` (30) or when a year the policy can
+reach is missing — the second condition is what lets a November notice land without a
+restart. The age threshold is read on every sync; the background cadence is fixed when the
+plugin loads, so changing it takes effect on the next reload. A year the dataset has not
+published yet — 2027 at the time of writing — comes back with no dates, and those days simply
+follow the weekday rule. That is the conservative reading: inventing a holiday would silently
+take providers out of rotation.
+
+The fetched calendar carries both halves of the arrangement: the closed days are idle, and
+the official 调休上班日 are working days, so a make-up Saturday is peak inside the normal
+windows while every other Saturday is idle. `peakMakeupWorkdays` remains a normal setting
+only as an escape hatch for an extra day of your own — it is unioned on top of the fetched
+make-up days. A date that is both a holiday and a make-up workday is idle: a statutory
+holiday wins.
+
+**The network can never break routing.** Every routing decision reads the in-memory calendar;
+a failed fetch keeps the cache and records the error, and a first run with neither a cache nor
+a network falls back to the plain weekday rule rather than failing a call. Settings shows the
+failure and offers **Sync now** to retry immediately.
+
+The holiday block of the Settings card reports **the current year only** — the status (synced
+/ stale / not synced / failed), that year's holiday and make-up counts, when it last updated,
+the source id, and the official notice URLs — plus a switch to keep it updating automatically
+and a **Sync now** button. Other loaded years stay in the payload because routing needs them
+(the peak lookahead crosses New Year), but the card shows one year so the figures answer "is
+today's calendar right" instead of "how much history is cached". A year the State Council has
+not published yet reads **尚未发布 / Not published yet** rather than "0 holidays". `holidayOverride`
+is the only hand-editable list: it adds extra
+**idle** dates on top of the fetched calendar for a one-off correction, and a refresh never
+clobbers it.
+
+`holidaySync: false` (or `holidaySource: 'off'`) turns the calendar off entirely: the
+fetched dates stop influencing routing, leaving only `holidayOverride` and the manual
+`peakMakeupWorkdays` list, so every other day follows the weekday rule. `holidaySource`
+normally names a source id (`holiday-cn`); giving it a full `https://` URL, or setting
+`holidayUrlTemplate` to a `{year}` template, points the sync at a mirror of your own.
+
+The period block above it shows the live reading — the current period, the local date and
+time, the configured windows, and when the period next flips (a Friday evening reports
+Monday 09:00, not the next midnight) — so you can see which ranking is actually in force. It
+also warns when today is a statutory holiday, or a make-up workday that the policy is still
+treating as idle. `peakEnabled: false` turns the overlay off entirely.
+
+#### How it composes with sticky
+
+Peak ranking does not fight `sticky`; it composes with it. With sticky on — the default —
+the period decides when a conversation **starts**, not what it does on every turn: a chat
+that began on the idle ranking keeps that provider when the peak window opens, because
+sticky pins the route that served its first call and already overrides `providerOrder` the
+same way. That is the whole point of sticky — re-deciding every turn throws away the
+provider's prompt cache. Turn sticky off and the provider changes exactly at the boundary;
+either way a new conversation honours the period on its first call.
+
+## Thinking depth
+
+The pool advertises the **union** of its candidates' thinking depths. Pick any depth you
+like; the router maps it to the **nearest tier the target actually supports** — exact
+match first, then the smallest rank distance, ties going to the higher tier. So `max` on
+a pool containing a route that only offers `off/high` becomes `high` for that attempt
+instead of failing with `UNSUPPORTED_REASONING_EFFORT`.
+
+The pool also advertises the **minimum** context window across its candidates, so a
+request that fits the pool always fits every route it may fail over to.
+
+## Images and other input
+
+The pool advertises the **union** of its candidates' input modalities, then routes each call
+to a candidate that can actually take it. Pick a pooled model whose routes include an
+image-capable provider and you can attach screenshots to it, without having to know or care
+which provider serves that turn.
+
+This is deliberate, and it used to be the opposite. The advertised set is what the Host
+checks *before* the call exists: a prompt carrying an image is refused outright with
+`MODEL_DOES_NOT_SUPPORT_IMAGES` when the selected model's `inputModalities` exists and omits
+`image`. Advertising the **intersection** of the candidates therefore made a model whose
+majority routes read images reject every upload — one text-only candidate (a regional
+gateway, a free tier) was enough to make the whole pool look blind. Advertising the **union**
+lets you attach the image, and the router then keeps that promise:
+
+- A text-only call keeps every candidate, so the pool still balances and fails over freely.
+- A call carrying an image is narrowed to the routes that accept one, *before* the strategy,
+  cooldown and sticky layers run, so the screenshot cannot silently become a placeholder.
+- A candidate that declares nothing is treated as text-only for an image call. Unknown is not
+  the same as capable, and guessing wrong costs the whole call.
+- If the only image-capable route is cooling down after a failure, it is still tried before a
+  healthy text-only one: a route that may have recovered beats an answer from a route that
+  never saw the image.
+- If nothing in a stale snapshot is capable, the pool still tries rather than refusing: the
+  runtime then degrades the image to a placeholder, which is recoverable, instead of the call
+  failing.
+
+Settings → Model Pool shows which candidates accept images, so a pool whose capability comes
+from a single route is visible rather than implied.
+
+## Seeing the live route in a conversation
+
+A pooled model is a virtual route, so the composer would otherwise only ever show
+"Model Pool · DeepSeek V4.1 Flash" with no hint of the real upstream. The plugin adds one
+entry to the composer dock (beside the built-in turn and token statistics) that shows what
+the **current session** actually ran on:
+
+```
+实际路由  workbuddy  deepseek-v4.1-flash  max  DeepSeek V4.1 Flash
+```
+
+- **Provider** — the concrete provider route that produced content.
+- **Model** — that provider's own id for it, which is often not the pool id.
+- **Thinking depth** — the effort actually used, when the route declares one.
+- **Pool model** — the row you selected, for context.
+
+The entry renders nothing when the session never ran through the pool, so ordinary
+conversations are untouched. It follows failover: if the first candidate fails before
+producing output, the badge shows the provider that actually answered, not the one that
+was tried first. The value is recorded per session, so two conversations open at once each
+show their own route.
+
+The badge describes the **conversation's** calls. Auxiliary calls that reuse the same pooled
+route — session-title generation, compaction summaries — pick their own thinking depth
+(usually `off`) and never define the entry, so a title call cannot make a conversation that
+ran at `High` report `Low`. The record is also settled the moment the answer's terminal
+chunk is produced, so a middleware that rewrites or re-wraps the answer stream cannot leave
+a stale value behind.
+
+The composer dock is polled every few seconds, so the value settles shortly after a turn
+finishes. It lives only in this Host generation — a restart clears it, and the entry is
+rebuilt on the next pooled call.
+
+## Availability markers
+
+Every concrete route carries a state:
+
+| State | Meaning |
+|---|---|
+| `ok` | Last attempt succeeded. |
+| `degraded` | Failed at least once; the cooldown has elapsed, so it is eligible again. |
+| `unavailable` | Failed and still inside the cooldown window; skipped while others are available. |
+| `unknown` | Never used in this Host generation. |
+
+A route that fails is recorded with its failure code (for example `AUTH`, `RATE_LIMIT`,
+`QUOTA`) and stays out of rotation for `cooldownMs`. If **every** candidate is cooling
+down the pool still tries them in strategy order — a transient outage must not become a
+hard failure. **Reset health** clears the markers.
+
+## Failover rules
+
+- A call fails over only while **no output has reached you yet**. Once text or a tool call
+  has streamed, the error is reported as-is: partial answers are never replayed.
+- `maxAttempts` bounds how many providers one call may try.
+- With `fallback: false` the first candidate is the only candidate.
+
+## Configure
+
+Settings → Model Pool covers the everyday knobs. The rest live in this plugin's own row
+in `cordis.patch.yml`, so they survive upgrades:
+
+```yaml
+- id: model-pool
+  name: dsh-model-pool
+  config:
+    strategy: least-used
+    fallback: true
+    skipUnavailable: true
+    cooldownMs: 60000
+    maxAttempts: 3
+    include: []            # provider allowlist; empty = all
+    exclude: [workbuddy]   # provider denylist
+    excludeModels: []      # model ids or substrings
+    providerOrder: [deepseek-account, workbuddy]  # priority ranking, highest first
+    peakEnabled: true
+    peakTimeZone: Asia/Shanghai
+    peakWindows: ['09:00-12:00', '14:00-18:00']   # peak windows; empty = never peak
+    peakWeekdays: [1, 2, 3, 4, 5]                 # ISO 1 = Mon … 7 = Sun; empty = never peak
+    peakMakeupWorkdays: []                        # extra 调休上班日; the fetched ones are automatic
+    peakProviderOrder: [workbuddy]                # ranking while peak; empty = inherit
+    offPeakProviderOrder: [deepseek-account]      # ranking while idle; empty = inherit
+    # Statutory calendar: fetched, not configured. Defaults shown; rarely changed.
+    holidaySync: true                             # keep the calendar up to date automatically
+    holidaySource: holiday-cn                     # or a source id, or 'off'
+    holidayUrlTemplate: ''                        # '{year}' template; empty = source default
+    holidayCacheDays: 30                          # refetch when the cache is older than this
+    holidayUpdateDays: 7                          # background refresh cadence
+    holidayOverride: []                           # one-off corrections, layered on the fetch
+    weights: { deepseek-account: 3, workbuddy: 1 }
+    costs:   { deepseek-account: 0.4, workbuddy: 0.1 }
+    modelGroups:
+      - id: deepseek-v4.1-flash
+        name: DeepSeek V4.1 Flash
+        models: [deepseek-v4.1-flash*, deepseek-flash]
+        merge: true
+      - id: fast-coding
+        name: fast-coding
+        models: [deepseek-v4.1-flash, glm-5.3-flash]
+        merge: false
+```
+
+### Merging one model that has several provider ids
+
+The same model usually carries a different id on each provider — one account calls it
+`deepseek-flash`, another `deepseek-v4.1-flash`, a third
+`opencode/deepseek-v4.1-flash-free`. Left alone those become three separate pool rows,
+which defeats the point of a pool.
+
+`modelGroups` fixes that. A group lists selectors that **claim** the matching routes and
+present them as a single row:
+
+| Selector form | Matches |
+|---|---|
+| `deepseek-v4.1-flash` | a concrete model id, or the normalized pool id |
+| `workbuddy/deepseek-v4.1-flash` | one exact `provider/model` route |
+| `deepseek-v4.1-flash*` | glob on any of the above (`*` = any run, `?` = one char) |
+
+With `merge: true` (the default) the claimed routes leave their single-id rows, so the
+pool shows one row per logical model. A natural row left with no routes disappears.
+Set `merge: false` when you want an *additional* curated pool ("fast-coding") and the
+automatic rows should stay.
+
+Selectors are matched first-come: if two groups claim the same route, the earlier group
+wins and the later one simply gets nothing from it.
+
+Two groups ship by default so this works out of the box — `deepseek-v4.1-flash*` +
+`deepseek-flash` merge into **DeepSeek V4.1 Flash**, and `glm-5.3-flash*` merges into
+**GLM 5.3 Flash**. Edit them in **Settings → Model Pool → Merged groups**, or replace
+the list in `cordis.patch.yml`. Changes are live: no restart.
+
+## How it works
+
+The Host's `llm` service exposes provider routes; the composer picker and Settings read
+them through `listProviders()` / `listModels()` / `resolveModelInfo()`. This plugin:
+
+1. Registers **one extra virtual route** (`model-pool`) whose models are the union of
+   every other provider's models, grouped by normalized model name. That is what makes
+   the pool appear in the ordinary picker, thinking-depth menu included. Each pooled model
+   advertises the union of its candidates' input modalities (see
+   [Images and other input](#images-and-other-input)), so a pooled model accepts a
+   screenshot when *any* of its providers can read one.
+2. Listens on the **`llm/stream` waterfall**. A request naming the pool route is
+   intercepted *before* dispatch and re-issued against a concrete provider chosen by the
+   strategy. A request that carries an image only considers the candidates that accept one,
+   so the advertised capability is honoured instead of merely declared. The runtime then
+   performs exactly one correct projection of files, images and tool history for the real
+   target.
+3. Keeps a **health registry** per concrete route, which feeds both the failover gate and
+   the Settings badges.
+
+The adapter's own `stream()` never runs; it exists only to claim the route so the catalog
+surfaces it. If it is ever reached, it fails with a clear message instead of silently
+returning nothing.
+
+See [`docs/CONTRACT.md`](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/docs/CONTRACT.md) for the verified API evidence and the full
+module contract.
+
+## Scope and limits
+
+- Pool state (health, round-robin cursor) is per Host generation: a restart clears it. The
+  fetched holiday calendar is the exception — it is cached on disk, so a restart reads it
+  instead of re-downloading. The very first sync needs network access; until it succeeds,
+  statutory holidays are simply not known and every weekday follows the weekday rule.
+- The pool re-reads the provider topology on `llm/adapters-updated`, so installing or
+  removing a provider updates the pools without a restart.
+- `providerId` / `providerName` changes need a restart to re-register the route.
+- Routing is per call, not per session: two calls in one turn may use different providers.
+  That is intentional for balancing, but it does mean a provider-side prompt cache is not
+  shared across a balanced pool. Use `priority` if cache reuse matters more than balance.
+- A pooled model's image support is the union of its candidates', so a conversation that
+  attached an image keeps working even when that turn fails over — but the *concrete* route
+  is narrowed per call, which means a sticky session may be moved onto a different provider
+  for an image turn and back afterwards. Sticky is a preference for cache reuse, not a
+  guarantee about capability.
+- The pool cannot know more than its providers declare. A route that advertises no
+  `inputModalities` counts as text-only for an image call; if such a provider in fact reads
+  images, the pool will not use it for them until that provider declares the capability.
+
+## Development
+
+```
+node --test test/*.test.mjs     # pure logic: grouping, strategies, health, effort,
+                                # capabilities, peak, calendar
+npm run check
+```
+
+## License
+
+MIT — see [`LICENSE`](https://github.com/BruceZhang1993/dsh-model-pool/blob/master/LICENSE).