diff --git a/AGENTS.md b/AGENTS.md index cba2c11..726a4c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,26 +108,26 @@ It is the same trick `test/architecture.test.ts` already uses for the client bun - `src/utils/request-shape.ts` — the fetch patch's PURE decisions, extracted so each branch is unit-testable on its own: which plane a URL belongs to (`isGoPlaneUrl`, `planeForUrl`), whether a route is Zen to the meter (`isZenProvider`, over `planeForRoute`), which credential header a protocol reads, the URL and header source of a `fetch` input, the model id and tool names a JSON body carries, the Anthropic version constant, a request's `x-opencode-plugin` marker (`pluginMarkerOn`, D27's pass-through), and the one table of plane headers both the patch and the plane adapter's per-call seam write (`planeHeadersFor`, its names read from the emulated row of `client-generation.ts`). Everything here is a function of its arguments — no context, no globals, no I/O. The rule it encodes: **a predicate that lives in a closure cannot be exercised alone**, so its branches survive until some integration path happens to take them. `hasSessionHeader` and `isOpenCodeRequest` were exported and tested; their six private siblings were not, and that was the difference. - `src/key-capture.ts` · `src/usage.ts` · `src/contracts/usage.ts` — credential extraction and its tier, the usage service, and the shared shape (with `USAGE_NAMESPACE`, `parseUsageReading`, the client's reading parser: the vendor whitelist `parseGoUsage` plus the fields the Host attaches, the allowance, `quotaUnavailable` and the plane spend; and `parseFailure`/`UsageFailure`, a refused read as the meter shows it). Quota discovery is `credentials.ts`'s fourth half. - `src/utils/credential-policy.ts` · `src/credentials.ts` — the credential rules every decider shares (P6), and their effects. The pure half holds the one placeholder filter (`usableKey`), the fill's and the meter's orders per policy, the capture gate (OC3: only a request of a turn the plugin decorated, never a foreign turn or a marked request) and L8's strike count (a captured key is dropped after a second well-formed 401 in a row on its plane, counted only on requests of decorated turns: the meter's own `/usage` poll and any other turnless request neither strike a key nor lift a drop). The effect half is the capture store, one per ROOT (`captureStoreFor(ctx)`, so a test's fresh `Context` is a fresh store and nothing process-wide needs clearing), the fetch patch's one resolver for an empty or placeholder wire key (`createCredentials`: observe, fill, settle, and the one read of the process environment the fill makes), the installation's store read, and the meter's discovery and key resolution (`discoverGoConfig`, `resolveGoBaseURL`, `resolveGoApiKey`, `resolveZenCreditInfo`; moved in from `go-discovery.ts` in P10a, held at a floor just under 100 for one unreachable guard, `result.status !== "fulfilled"` in `resolveGoKeyForRef`, since the credentials resolver never rejects; the move's other undriven branch, the reachable `readProviderRow` else for a nested `options` block with no usable key, is driven now, and `vite.config.ts` keeps the measured list). The plane adapter never asks it: its key is pi-ai's rule (D20). `test/credential-parity.test.ts` pins all four deciders side by side and was written before the move. -- `src/catalog-data.ts` · `src/models-catalog.ts` · `src/host/discovery.ts` — the generated static shim, the OpenCode-catalog parser with SWR refresh (with the one spec lookup, `specOn`/`specFor`, a plane's row then the plane-blind one, and `liveCatalogOn`), and the Settings discovery wrapper (behind `enrichModels`; off, Fetch is pi's list and `NO_DISCOVERY` passes through): on a plane the plugin serves, Settings → Models → Fetch answers pi's list plus the catalog's servable, non-deprecated models pi lacks (D3, P3), and the catalog alone while pi-ai restarts. `catalog-data.ts` is **generated**; never hand-edit it. +- `src/catalog-data.ts` · `src/models-catalog.ts` · `src/host/discovery.ts` — the generated static shim, the OpenCode-catalog parser with SWR refresh (the parse is pure and answers each plane's retired ids, `deprecated`; the live catalog is one state per plane, its rows and its retired ids, seeded from the shim and REPLACED by a refresh that carries at least one active row for that plane, never merged, so a failed or empty read replaces nothing, L12; `refreshCatalog` resolves a `CatalogRefresh`, `{ ok, deprecated, go, zen }`, read from the state after the attempt, and keeps the reason it did not land both planes beside it, `catalogLastError`; the shim's retired ids are read off the module namespace, `shippedDeprecatedIds`, absent meaning none, until CI regenerates the shim with them; with the one spec lookup, `specOn`/`specFor`, a plane's row then the plane-blind one, and `liveCatalogOn`), and the Settings discovery wrapper (behind `enrichModels`; off, Fetch is pi's list and `NO_DISCOVERY` passes through): on a plane the plugin serves, Settings → Models → Fetch answers pi's list plus the catalog's servable, non-deprecated models pi lacks (D3, P3), and the catalog alone while pi-ai restarts. `catalog-data.ts` is **generated**; never hand-edit it. - A note on the sweep that found the two entries around here, because it nearly produced a false one: grepping for a symbol's callers while EXCLUDING the file that defines it makes every same-file call look like no call at all. `resolveGoKeyForRef` reads as unreferenced that way and is not — `resolveGoApiKey` calls it (both in `credentials.ts`), and the usage service calls that. (An earlier version of this line said that is "how the Go endpoint keeps Zen keys away from itself"; there is no such exclusion, and the note below records why.) Check the defining file too before believing an export is dead. **The general form, because this shape recurred twice in one session**: a sweep that resolves a name in the wrong CONTEXT reports a clean tree as broken. Grepping for callers without the defining file makes same-file calls look absent; resolving a doc's relative links from the repository root instead of from the file's own directory makes every link look dead. Both produced a list of confident findings and both were entirely wrong. A third instance is reading a UTC timestamp as local time and concluding that a workflow had not run since the previous evening, when it had run twenty minutes earlier — same shape, wrong context, confident conclusion. Before acting on a sweep, check that the thing being searched is the thing the claim is about, including the clock it is written in. - `src/go-limits.ts` — the allowance lookup and the label normalization; the money formatting is `utils/usd.ts`'s `allowance` style. **One lookup, and it is the tested one**: `attachAllowance` in `usage.ts` used to inline the same expression, and the copy nothing called was the tested one; it now goes through `allowanceFor`. The row's label is the model the allowance belongs to — the picked one, by the catalog's spelling — because a figure beside another model's name states something false about the money. - `src/go-limits-data.ts` — the Go plan allowances, per model and per tier, **generated** from the vendor's own page by `scripts/generate-go-limits.ts`; never hand-edit it, and regenerate with `pnpm run limits:shim -- --write`. The scheduled freshness job is what notices when the page moves, which it did: the docs went under `/v2/docs/console/` and serve HTML now, so the generator reads a table off that page rather than the markdown it used to. Then the old URL answered 200 again with a body that has no tab sections (2026-11-07), so the sources are asked in turn, the moved page first (`firstDoc`), and a 2xx answer is read by what its body carries; the status alone is never trusted (`docFrom`, both in `scripts/go-limits-html.ts`). Then the page carried three allowance tables where it had carried two (2026-11-12), so each is chosen by the plan label the page attaches to it rather than by position or count (`chooseTables`): the tab its panel names, else the panel's own label, else the heading before it (one inside another tab's panel labels nothing outside it), Go and Go Plus each exactly once, tables labelled with another plan ignored, and only two tables with no plan label and no tab label (a heading that names no plan is not one) kept in the measured order. The Starlight tab markup that labelling reads is assumed, not measured, until a live run logs it: every log line names each table's label, rows and first row. Both old URLs now redirect to `https://opencode.ai/docs/console/go/`, which is the one asked first. -- `scripts/generator-kit.ts` · `scripts/catalog-shim.ts` — what the two generators and `scripts/verify-catalog.ts` share: their arguments (`generatorArgs`), the source read (`readSource`), and the ONE staleness rule (`stale`: canonical data differs; key order and formatting never count), with the exit and action it leads to (`outcome`: a file current in data and in text is never rewritten; without `--write` a template change is still `current`, and with `--write` current data in text that is not the renderer's is `rewrite`, which only the limits generator, the one whole-file renderer, does). `catalog-shim.ts` is the catalog generator's pure half — the renderer and the splices, moved verbatim, and `shimStale` over every export the shim carries, the plane and family endpoints included. `test/generators.test.ts` holds both, spawns both generators with `--from` (a source that disagrees with the shipped data exits 1, for the catalog the same ids with only a plane or a family endpoint moved; the limits generator's doc made from the shipped table and the catalog payload that reproduces the shim exit 0) and the limits generator's `--write` from a scratch copy of `scripts/` and `src/` (a template change rewritten, a moved figure written), round-trips each renderer through the formatter against the committed file (`scripts/go-limits-render.ts` is the limits generator's renderer), and spawns `verify-catalog` (offline only: `--from`, `--offline`), passing on the payload that reproduces the shim and failing on a moved endpoint. +- `scripts/generator-kit.ts` · `scripts/catalog-shim.ts` — what the two generators and `scripts/verify-catalog.ts` share: their arguments (`generatorArgs`), the source read (`readSource`), and the ONE staleness rule (`stale`: canonical data differs; key order and formatting never count), with the exit and action it leads to (`outcome`: a file current in data and in text is never rewritten; without `--write` a template change is still `current`, and with `--write` current data in text that is not the renderer's is `rewrite`, which only the limits generator, the one whole-file renderer, does). `catalog-shim.ts` is the catalog generator's pure half — the renderer and the splices, and `shimStale` over the five values the shim carries (both catalogs, the plane and family endpoints, and the retired ids, `OPENCODE_DEPRECATED_IDS`), each read from the generated file through one function (`shippedShim`, an absent retired-ids export read as none), and the whole generated output through one more (`rewriteShim`, whose `upsertObject` adds the retired-ids export to a shim that predates it, so CI's `--write` needs no hand edit). `test/generators.test.ts` holds both, spawns both generators with `--from` (a source that disagrees with the shipped data exits 1, for the catalog the same ids with only a plane or a family endpoint moved; the limits generator's doc made from the shipped table and the catalog payload that reproduces the shim exit 0) and the limits generator's `--write` from a scratch copy of `scripts/` and `src/` (a template change rewritten, a moved figure written), round-trips each renderer through the formatter against the committed file (`scripts/go-limits-render.ts` is the limits generator's renderer), and spawns `verify-catalog` (offline only: `--from`, `--offline`), passing on the payload that reproduces the shim and failing on a moved endpoint. - `scripts/session-band.ts` — `verify-session-band.ts`'s pure half: the vendor's id construction, ported, the four band facts with the answer each must have (`bandMismatches`), and the verdict the script prints (`bandVerdict`): "CONFIRMED" only when there is no mismatch, otherwise one `MISMATCH:` line each and exit 1. The unit run makes the verdict fail on a planted derivation, spawns the script in its passing state, and spawns a scratch copy of it beside a `src/session.ts` whose derivation leaves the band, which prints the `MISMATCH:` line and exits 1. - `scripts/freshness-scope.ts` — which of CI's three freshness checks (`catalog:shim`, `limits:shim`, `cli:version`) a pull request is GATED on: the ones whose inputs (the check's script and the local modules it loads, walked from the source as Node loads it — types erased by Node's own stripper, specifiers read by `es-module-lexer` — plus `src/identity.ts` for the CLI version; never the generated files) its own diff touches. The rest only warn, because vendor drift is not the pull request's regression: for the two generated tables the nightly run regenerates them and proposes the refresh, and for the CLI version it warns and the bump is a human pull request, which then gates. The gates fail closed: each runs unless the scope step answered `report`. The CLI version's offline half — every copy in the tree agrees with the pin, `cli:version -- --copies` — gates every pull request, since it skips the generated tables and only the repository can break it. `test/freshness-scope.test.ts` walks the real generators, runs the scope step's own shell and the CLI it calls, and evaluates the workflow's step conditions. - `src/host/route-claim.ts` · `src/host/plane-provider.ts` · `src/host/describe-graft.ts` · `src/host/host-modules.ts` — the plugin owns the plane routes (D13). The route claim appends ONE `internal/config` listener that reads either cordis core's call shape (`src/utils/config-run.ts`: `function (this: Fiber, raw, next)` on the OLD core, `(fiber, next)` with `this` null on the NEW one), calls `next()` exactly once, re-appends itself whenever pi-ai reaches `internal/status` ACTIVE so it stays inner to pi-ai's own checking listener (the new registration first, the old one released only once the host accepted it, so a refusal while the plugin's fiber is going away throws nothing into pi-ai's emit), and hands `llm-pi-ai`'s fiber a copy of what `next()` answered without the `opencode`/`opencode-go` entries it TAKES — an entry another plugin owns (D27: pi-ai's row resolving `credentials` in a realm the plugin's context does not, compared by the key each context reads off cordis's realm map so a group's `isolate` counts, or an entry carrying the `x-opencode-plugin` header, `src/utils/plane-ownership.ts`) stays pi-ai's, is logged once, and is never counted by a restart, a handback or the reconcile; a commit run releases at once a plane the plugin registered that its candidate no longer lets it take, so pi-ai's registration of it meets no duplicate; and the claim's read-only `steppedAside()` accessor makes the stream hook run such a turn undecorated under a `foreign` turn state (`turn-store.ts`), which the fetch patch passes through before its URL claim, as it does any marked request, and keeps the 1.x discovery wrapper off its Fetch; a commit run (the fiber's raw config, the loader's stored row config, or any run while the fiber is not ACTIVE) never throws, and every fiber config is read through the feature-detected accessors, validates a Settings edit to a plane with pi-ai's own checks, and registers the plane adapter for exactly the declared planes through `registerAdapter`/`handle.replace`; on dispose it hands the planes back by restarting pi-ai (never on a reload). `plane-provider.ts` is `PlaneAdapter`, a subclass of the host's `PiAiAdapter` over pi's own `createProvider` and four protocol implementations, with the credential seams that mirror pi-ai's (D20), and pi-ai's `prepareHeaders` option, as pi-ai's own adapter has it (`planeRequestHeaders`): per call, the plane headers of the turn the stream hook decorated (OC5, written by `lifecycle.ts` from `planeHeadersFor`), then the host's `llm-pi-ai/request-headers` waterfall, so another plugin's contributor runs on the planes the plugin serves (OC4), detected by behaviour; its `prepareCall` stream and `stream` finish the gateway's typed refusals as `FREE_TIER` or `MODEL_UNAVAILABLE` with the gateway's words, and its status except on Google-protocol models, whose failure text carries none (`src/utils/gateway-refusal.ts`), because the conversation replaces an AUTH failure's message with "API key is invalid". Its stand-in (`test/support/route-claim-stand-in.ts`, driving `test/route-claim*.test.ts`; the new core's call-shape cases are in `test/route-claim-listener.test.ts`) builds fibers of both cores — `piFiber` (the OLD core's `_config` and resolved `config`, driven through `oldRun`) and `newPiFiber` (the NEW core's raw `config`, `rawConfig` and `effectiveConfig`, no `_config`, driven through the stand-in's `waterfall`, whose per-listener `next` throws on a second call, and its `internal/status` emit) — and `test/host-planes.test.ts` runs the claim on the installed host, whichever core it is. `describe-graft.ts` is the one read-only `settings.describe` wrapper that keeps Settings showing the planes (D18). `host-modules.ts` is where the host's own modules are found — pi-ai's on its loader entry, pi, dsh-llm and the loader from the wrapper's own tree — behind the replaceable seam in `src/cordis-context.ts` (`replaceHostModuleSource`), which is how tier A runs the claim. What a protocol sends, Google's thinking control included, is the host's pi's own (D26): where a host's pi lacks something the gateway needs, the suite records a `[HOST_LIMITATION]` row and skips the cases that would exercise it by pi's own exported predicate, never a version compare. - `src/contracts/remote.ts` · `src/contracts/all.ts` · `src/settings-remote.ts` — one remote seam (P9). `defineRemote(namespace, methods)` builds a contract from each method's parameters and result parser and DERIVES the descriptors the client mounts; `REMOTE_CONTRACTS` is the one list the client's `patchRemote` is built from. A new remote is one `defineRemote`, one entry in `all.ts`, one `markRemote` on its service and one `installRemoteService` in `lifecycle.ts`. On the client, `callRemote` finds the call (through `ctx.get` first, see `remoteNamespaceOf`), calls it with no argument unless one is given (the gateway checks arity), and `unwrapRemote` is the one unwrap of the `{ ok, value | error }` envelope, parsing the payload with the contract's own result parser. The two usage callers (the settings summary and the meter) do not use `callRemote`: they go `findRemoteCall`, then `callUsageRead` (the arity retry that tolerates the sibling `dsh-opencode-go`'s zero-parameter registration of the same `read`), then `unwrapRemote`; and the meter passes an `invalid` payload through to the pill unchanged until P11. Client-safe, so the bundle loads them. - `src/host/remote.ts` — `markRemote`, which writes a service's Remote marker from its contract (the decorator is rejected by the build transform; the type makes a contract method the class lacks a compile error), and `installRemoteService`, the one installer for the usage, purge and store-inspection services. One service per root, alive while a live activation holds it, reading the latest live activation's options and disposed with the last; checked against the client contract's namespace after the mount settles and reported through the activation's logger; no `ctx.provide` fallback, because a provided value is invisible to the Gateway's discovery. -- `src/purge-service.ts` · `src/contracts/purge.ts` — the card's "purge deprecated models" action, and the shape it answers with. It **rewrites the profile**, deleting the declared model entries the live catalog has retired, through `configEditor` (the same service the settings UI writes with). That is deliberate: a read-time filter would leave the declaration in place, and then the only way to explain a missing row is to find the filter. One source of truth, and it is the configuration. It never rewrites a plane entry another plugin owns (D27: the `x-opencode-plugin` marker, or a row whose credentials resolve in a realm the service's context does not), nor a reference to a route only such entries declare. +- `src/purge-service.ts` · `src/contracts/purge.ts` — the card's "purge deprecated models" action, and the shape it answers with. It **rewrites the profile**, deleting the declared model entries the live catalog has retired, through `configEditor` (the same service the settings UI writes with). That is deliberate: a read-time filter would leave the declaration in place, and then the only way to explain a missing row is to find the filter. One source of truth, and it is the configuration. It judges by its own forced refresh's answer (`CatalogRefresh.deprecated`: the registry's when the read lands, what the process holds when it does not, `catalogRead` saying which), and writes each entry at most once: `purgeEntryConfig` is the pure rewrite of one entry (its declarations on the routes it owns, then every reference), run as a pre-check that skips an entry with nothing to remove and again inside that entry's one `edit`. `review` lists the ids declared on the plugin's own plane entries that pi's installed catalog cannot serve (`piUnservedIds`, read through `loadHostLibraries`) and the catalog's last error, and `removeUnserved` runs the same one-edit-per-entry rewrite with that list as its judge; the card shows both under the purge row, the step before removing the plugin. It never rewrites a plane entry another plugin owns (D27: the `x-opencode-plugin` marker, or a row whose credentials resolve in a realm the service's context does not), nor a reference to a route only such entries declare. - `src/session-cost.ts` · `src/cordis-context.ts` · `src/debug.ts` — per-turn accounting, the typed host interfaces, and stream debug logging. - `src/host/global-fetch.ts` — `installGlobalFetch`, the plugin's one write to `globalThis.fetch` (P6). It reads the fetch it wraps inside the effect, keeps a chain of its links, turns a link disposed under another into a pass-through, and on a restore unwinds through disposed links, so apply A, apply B, dispose A, dispose B ends at the fetch that was there, in either order, and a function the plugin did not install is never replaced. It is the one named exemption of the host-write tripwire below, which stays while the patch keeps relays, listing enrichment, the credential fill, the body fallback and the User-Agent. - `src/host/patch-method.ts` — `patchMethod`, the one way to wrap a method on a host object. A dispose restores only while its wrapper is still the current value (otherwise it becomes a pass-through under whatever wrapped on top), and deletes the own property when the original was inherited rather than assigning it back; a second install of the same site wraps the unpatched method instead of the first install. Identity is read from own descriptors, never from a property read, because cordis's traceable proxy answers a fresh proxy for every method read (`docs/engineering-notes.md`). `rewrapOnAdaptersUpdated` reinstalls a site on `llm/adapters-updated`, for a site that must follow the registry; none uses it yet. Every instance patch in `src/` goes through this module — today two sites: model discovery (`host/discovery.ts`) and the `settings.describe` graft (`host/describe-graft.ts`) — and `test/reload.test.ts` runs apply A, apply B, dispose A, dispose B on each. Two tripwires hold the rule. `test/architecture.test.ts` is textual: anywhere `apply()` reaches but the helper, it fails on a `Reflect.set`/`defineProperty`/`deleteProperty`/`setPrototypeOf`, an `Object.assign`/`defineProperty`/`defineProperties`/`setPrototypeOf` onto `llm`, an adapter, `settings` or `globalThis` (bare or through a property path such as `registration?.adapter`; a prototype swap shadows a method without leaving an own property), a dotted or bracketed assignment (through `?.` or `!` too) onto the first three, and `globalThis.x =` (the global `fetch` installer, `host/global-fetch.ts`, is the one named exemption); a write through a local alias or a cast receiver escapes it. The `apply()`-twice reload case is behavioural: it requires the helper's record on every own function `apply()` leaves on the stand-in's `llm` and `settings`. - `src/utils/planes.ts` · `src/utils/usd.ts` · `src/utils/client-generation.ts` · `src/utils/context-windows.ts` — P7's one source per table, each held at 100% coverage. `planes.ts` is `PLANE_OF_ROUTE`, read exactly through `planeOfPlaneRoute` (the two owned routes, never an inherited key) or with relays through `planeForRoute` (`opencode-go` and `opencode-go-*` are Go, everything else Zen, case-sensitive), or indexed directly where the route is already a typed `PlaneRoute`; `test/planes.test.ts` scans `src` for a second copy of the rule in the spellings it names (a comparison against a plane route's literal, the relay half `startsWith("opencode-go…")`, a `case` label, and a quoted route paired with a plane's name in a table row, in either order and under any key name); each allowed file's count is exact, so a copy added inside an allowed file is seen and a copy that goes forces its allowance down. The scan is a tripwire for the spellings it names, not a proof: what passes it includes, for example, an unquoted key, a record with another key between the route and the plane, and a route built from parts, and the test plants each of those as a non-offender. (The relay predicate, `!provider.startsWith("opencode")` in both writers of `request/headers.ts`, asks a different question and is left inline.) `usd.ts` is `formatUsd(value, style)`, `allowance` (a whole figure drops the cents, an unknown one is "—") or `metered` (always two decimals), and every caller names its style. `client-generation.ts` is `CLIENT_GENERATIONS`: the plugin emulates `1.x`, whose row `planeHeadersFor` and `identity.ts` read; the `2.x` row, and `sessionValue` in either row, is recorded and read by nothing; it pins no 2.x version (its User-Agent is a format, not a value), and no test or source writes a concrete 2.x literal (`pnpm run cli:version` refuses one). `context-windows.ts` is `MEASURED_CONTEXT_WINDOWS` and `measuredWindowFor`, read ahead of the catalog's window by `plane-model.ts`, and in the catalog's place in each field order by the discovery rows (so pi's window still wins on a route pi-ai serves); both take the table as a parameter, and a row is added only with its measurement. - `src/utils/config-run.ts` — an `internal/config` run and a fiber's three configs, read the same way on either cordis core, held at 100% coverage: `configRunOf` decodes the call (the fiber is `this` on the OLD shape, the first argument on the NEW one, `next` the last argument on both), `isFiber` is the structural fiber predicate (`fiber.ctx.fiber === fiber`), `rawConfigOf`/`effectiveConfigOf` are the feature-detected accessors (`rawConfig` else `_config`, `effectiveConfig` else `config`), `entryConfigOf` reads the loader's stored row config (`fiber.entry.options.config`), and `isCommitRun` tells a commit from an editor candidate by identity. `test/support/config-shape.ts` re-exports the predicate and the accessors, so a contract and the claim never read a fiber two ways. Told apart by the call and the fiber's own fields, never by a version. -- `src/utils/protocols.ts` · `src/utils/model-metadata.ts` · `src/utils/plane-model.ts` · `src/utils/plane-profile.ts` · `src/utils/plane-ownership.ts` · `src/utils/gateway-refusal.ts` — the plane's pure decisions, each held at 100% coverage: the code a gateway refusal finishes with (its type token in pi's failure text, the status at the text's head; Google's text carries none), which declared plane entries the claim takes and which another plugin owns (the `credentials` realm each context resolves, read off cordis's realm map with the rows' labels as the fallback, and the `x-opencode-plugin` marker, D27; `credentials.ts` asks the same two questions so the meter never reads another plugin's entry), the SDK → protocol table and the per-protocol base tables (every value measured; see `docs/redirect-planes.md`), the reasoning efforts a model offers (D1), the pi model object one declared model becomes (protocol from the catalog, then the route's `api`, and the base from the endpoint family table, never from pi's own catalog, D16, D26; metadata from the user's row first, D17; the family `auto` resolves to, `AUTO_ENDPOINT_FAMILY`, P-R2), and the profile one plane entry becomes, with pi-ai's own checks and messages for every malformed field, never throwing; the default window and output tokens are the ones pi-ai's own `Config` fills in, never a copy (D17), and so are the image-count bounds (`maxRequestImages`, and `imageOffloadCountQuantum` derived from it as pi-ai's own profile resolution does) wherever the installed pi-ai's `Config` fills them and absent where it does not. +- `src/utils/protocols.ts` · `src/utils/model-metadata.ts` · `src/utils/plane-model.ts` · `src/utils/plane-profile.ts` · `src/utils/plane-ownership.ts` · `src/utils/gateway-refusal.ts` — the plane's pure decisions, each held at 100% coverage: the code a gateway refusal finishes with (its type token in pi's failure text, the status at the text's head; Google's text carries none), which declared plane entries the claim takes and which another plugin owns (the `credentials` realm each context resolves, read off cordis's realm map with the rows' labels as the fallback, and the `x-opencode-plugin` marker, D27; `credentials.ts` asks the same two questions so the meter never reads another plugin's entry), the SDK → protocol table and the per-protocol base tables (every value measured; see `docs/redirect-planes.md`), the reasoning efforts a model offers (D1), the pi model object one declared model becomes (protocol from the catalog, then the route's `api`, and the base from the endpoint family table, never from pi's own catalog, D16, D26; metadata from the user's row first, D17; the family `auto` resolves to, `AUTO_ENDPOINT_FAMILY`, P-R2), and the profile one plane entry becomes, with pi-ai's own checks and messages for every malformed field, never throwing, and the ids a plane entry declares that pi-ai cannot serve without the plugin (`piUnservedIds`, its "needs an api" rule mirrored); the default window and output tokens are the ones pi-ai's own `Config` fills in, never a copy (D17), and so are the image-count bounds (`maxRequestImages`, and `imageOffloadCountQuantum` derived from it as pi-ai's own profile resolution does) wherever the installed pi-ai's `Config` fills them and absent where it does not. - `src/attachment-services.ts` — optional attachment and filesystem services for the plane adapter's image requests, captured through Cordis child scopes. - `src/opencode-paths.ts` — where an OpenCode installation keeps its files, ported from `~/dev/opencode`'s `global-roots.ts` (the directory) and `database-path.ts` (the filename). It takes `home`, `env` and `channel` as parameters and reads neither the environment nor the filesystem, which is what makes the Windows and Linux layouts testable from here. Two facts it encodes that are easy to get wrong: the directory is XDG on EVERY platform — macOS and Windows use `~/.local/share` too, and `os.homedir()` is the only platform-dependent call — and the FILENAME is not constant, being `$OPENCODE_DB`, else `opencode.db` on a stable channel, else `opencode-.db`. The database sits under `data` while the config sits under `config`, so one root cannot serve both. It is the foundation of the opt-in reader: `credentials.ts`'s `resolveOpencodeStoreKey` imports it, and so does `opencode-store-service.ts` (the inspection's path); nothing else does. - `src/opencode-store.ts` — reading the credentials an OpenCode installation already holds, through `node:sqlite`. Two rules shape it: nothing throws (a missing file, a foreign schema and `:memory:` all answer `undefined`), and a value never leaves the return value — no log line, no error message, no client bundle. `node:sqlite` is host-only, which is what keeps the module on the host side of the bundle rule. It is reached only through `resolveOpencodeStoreKey`, which is the last step of every key-source policy and is off unless `readOpencodeStore` is on. Its second reader, `inspectOpencodeStore`, answers the _other_ question — "is there a credential here, and whose is it?" — with a sanitized summary (email, org, kind, expiry) and never the token, which is what lets the settings card show the evidence beside the permission. diff --git a/README.md b/README.md index 9c64467..04cefac 100644 --- a/README.md +++ b/README.md @@ -397,7 +397,9 @@ Disabling or removing the plugin hands both planes back to `llm-pi-ai`, with not - **`llm-pi-ai` serves the ids it knows again**, on its own adapter, endpoint family and reasoning rules. - **Ids it cannot serve drop out of the composer.** That is an id its installed catalog does not describe — a catalog-unknown id, or a newer model than its pi carries — including a model adopted from Settings' fetch that pi does not list. -- **The next Settings edit of that plane is refused until they are removed**, because `llm-pi-ai` validates the whole plane entry on every save. Delete those ids from the plane's model list, and the edit goes through. +- **The next Settings edit of that plane is refused until they are removed**, because `llm-pi-ai` validates the whole plane entry on every save. Remove them with the settings card (below) or delete them from the plane's model list by hand, and the edit goes through. + +**Before removing it, the settings card lists those ids.** Under the purge row, **Models llm-pi-ai cannot serve** names every id your own `opencode` and `opencode-go` entries declare that pi's installed catalog does not describe (a plane entry with a route-level `api` has none: `llm-pi-ai` serves every id on it), and **Remove** deletes them, and every reference to them (a subagent's allowed model, the compaction summariser), with one profile write per entry. It is the step before removing the plugin: while the plugin is installed it serves those models, so removing them takes them out of the composer. A plane left with no declared model offers its whole catalog, as an entry that declares none always does: pi's installed one once the plugin is gone. When pi's catalog cannot be read the card lists and removes nothing, and says so under the purge row. ## With OpenCode Console installed @@ -423,7 +425,7 @@ OpenCode's own Console plugin (`npx @opencode/console setup deepseek-harness`) c | `400 MissingSessionID` | No session header attached | Ensure `dsh-opencode-patch` is listed in the profile's `dsh.profile.bundles` | | Auto Review fails with `TRANSPORT: Connection error` | Host process not restarted since the update | Stop and restart `dsh web` so the new `lib/index.mjs` loads | | Quota ring never appears for a Go model | **Restart `dsh web`, then read the browser console** — the plugin is loaded through a `link:`, so `lib/index.mjs` is read once at process start and a page reload alone keeps the old host code; the meter reports which of its paths returned nothing | The console names the cause: `no remote to mount on`, `did not mount` with the exception, `still waiting for remote.opencodeGoUsage`, `no opencodeGoUsage service on the remote` with the keys it does expose, or `the answer is not a usage shape` with what came back. A missing or unroutable credential is one cause of several, not the only one: name `apiKeyEnv: OPENCODE_GO_API_KEY` on the `opencode-go` entry and store that key in DSH Credentials | -| A catalog model is missing from Settings → Fetch, or a retired one persists | Stale host module, enrichment off, the route is not a plane the plugin serves (only `opencode`/`opencode-go` on the served `llm-pi-ai` row are complemented, and never a route left to another plugin such as OpenCode Console), or the catalog has not been read yet (offline, or `models.opencode.ai` blocked), so pi's own list, retired ids included, passes through and models newer than the bundled catalog are absent | `pnpm run build`, restart `dsh web`, keep **Enrich listings from the OpenCode catalog** on, fetch from the matching route, search the exact id (e.g. `gpt-5.3-codex-spark`); if the catalog is unread, then once `models.opencode.ai` is reachable fetch once to start the catalog refresh (that answer is still the old list — the refresh runs behind the read, and nothing runs it on a timer), then fetch again a moment later | +| A catalog model is missing from Settings → Fetch, or a retired one persists | Stale host module, enrichment off, the route is not a plane the plugin serves (only `opencode`/`opencode-go` on the served `llm-pi-ai` row are complemented, and never a route left to another plugin such as OpenCode Console), or the catalog has not been read yet (offline, or `models.opencode.ai` blocked), so pi's own list passes through, less the ids the bundled catalog itself records as retired, and models newer than the bundled catalog are absent (the card names the last refresh's error under the purge row) | `pnpm run build`, restart `dsh web`, keep **Enrich listings from the OpenCode catalog** on, fetch from the matching route, search the exact id (e.g. `gpt-5.3-codex-spark`); if the catalog is unread, then once `models.opencode.ai` is reachable fetch once to start the catalog refresh (that answer is still the old list — the refresh runs behind the read, and nothing runs it on a timer), then fetch again a moment later | | Popover shows “Limit reached” in red | 100% of a rolling/monthly window reached | Open the [OpenCode Console](https://opencode.ai/console) and enable _Use balance_ to overflow into Zen credits | | Non-OpenCode models misbehaving | Unrelated to this patch | Traffic to other providers passes through untouched | @@ -450,6 +452,7 @@ OpenCode's own Console plugin (`npx @opencode/console setup deepseek-harness`) c - **The gateway's refusals are reported as what they are.** On the planes this plugin serves, a `FreeTierError` (403) or `FreeUsageLimitError` (429) now finishes the turn as `FREE_TIER`, and a `RegionError`, `ModelDeprecated` or `ModelProtocolUnsupported` as `MODEL_UNAVAILABLE`, each with the gateway's words, and its status except on Google-protocol models, whose failure text carries none. The conversation used to show "API key is invalid" for the 403s and "Request quota exhausted." for the usage cap, with the gateway's message dropped. Like the codes they replace, neither new code is in the host's retryable set, so a refused turn is still not resent. A free Chat Completions turn with no tools of its own now carries `tool_choice: none` beside the free tier's `read` and `bash`, and a `read` or `bash` declared with an empty schema is replaced by the full one. - **A key seen on a request is kept only from the plugin's own turns, and dropped after two refusals.** The plugin used to record the key of every request it claimed, a request outside any turn included, and to replay the latest one onto any request a configured provider claimed; it now records a key only from a request of a turn it decorated, fills a request on neither plane only with a key its own route sent there and never fills a gateway request or the meter with such a relay key (a route named `opencode` or `opencode-go` is the exception: its key is that plane's even when its own `baseURL` points elsewhere, as a mirror's would be), and drops a captured key after the gateway refuses it twice in a row on its plane, on its own turns' requests: a request outside them, the usage meter's own poll included, never counts against a key. A blank exported key or a placeholder in the installation's store no longer goes out as a credential, and a blank or placeholder `OPENCODE_API_KEY` no longer counts as Zen credit for the meter's overflow card. Disabling two overlapping activations in either order now leaves the `fetch` that was there before them. - **The planes' headers are set per call, and other plugins' `llm-pi-ai/request-headers` contributors run there.** On the planes this plugin serves, its session, origin and project headers are written through `llm-pi-ai`'s per-call header seam, as `llm-pi-ai`'s own routes write theirs, and another plugin's contributor to that seam now runs on them too: one that throws fails the turn with `REQUEST_HEADERS`, as it already did on `llm-pi-ai`'s routes. The seam first shipped in harness `0.2.2-alpha.3` and `0.2.2-rc.1`. The supported range is unchanged: on an older host (`0.2.2-alpha.2` or a `0.2.1` build), the plugin's own headers still go out, written by its fetch patch as before, and other plugins' contributors do not run on the planes there, because that host never asks for them (see the seam's floor below). +- **The purge writes each entry once, judges by the catalog read it makes, and the card lists the models `llm-pi-ai` cannot serve.** The purge used to edit an entry up to twice (its declarations, then its references) and to rewrite every entry that declared a plane, retired model or not; it now leaves an entry with nothing retired untouched and writes one with something retired once. A catalog refresh now replaces each plane it carries models for, so a model the registry stops listing or retires leaves the catalog on that refresh rather than staying until a restart, and a failed or empty read changes nothing. Under the purge row, the card shows the catalog's last refresh error, and lists the declared ids pi cannot serve with a **Remove** action (see [Removing or disabling the plugin](#removing-or-disabling-the-plugin)). - **Usage settings apply when the plugin is applied again, and disabling the plugin withdraws its services.** A change to `usageBaseURL`, `keySource` or `readOpencodeStore`, or turning `usageEnabled` off, takes effect the next time the plugin is applied: when it is disabled and enabled again, or when `dsh` restarts. The usage service used to keep the values it started with until `dsh` restarted, however often the plugin was disabled and enabled in between. Disabling the plugin now withdraws its usage, purge and store-inspection services instead of leaving them answering. ## 📜 Compatibility & Verification diff --git a/README.zh-CN.md b/README.zh-CN.md index 7243fbc..8c7c78d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -391,7 +391,9 @@ Zen 路线上不出现任何 Go 的数字:根本不画圆环(没有可量的 - **`llm-pi-ai` 重新服务它认识的 id**,使用它自己的适配器、端点家族与推理规则。 - **它服务不了的 id 会从输入框的模型列表中消失。** 也就是它内置目录未描述的 id——目录未知的 id,或比它的 pi 更新的模型——包括从设置的获取中采纳、而 pi 未列出的模型。 -- **在删除这些 id 之前,对该平面的下一次设置编辑会被拒绝**,因为 `llm-pi-ai` 每次保存都会校验整个平面条目。把这些 id 从平面的模型列表中删掉,编辑即可通过。 +- **在删除这些 id 之前,对该平面的下一次设置编辑会被拒绝**,因为 `llm-pi-ai` 每次保存都会校验整个平面条目。用设置卡片(见下文)移除它们,或手动把它们从平面的模型列表中删掉,编辑即可通过。 + +**移除插件之前,设置卡片会列出这些 id。** 在清理一行下方,**llm-pi-ai 无法提供的模型**列出你自己的 `opencode` 与 `opencode-go` 条目所声明、而 pi 已安装目录未描述的每个 id(带路由级 `api` 的平面条目没有这类 id:`llm-pi-ai` 能服务其上的每个 id),**移除**会删掉它们以及所有对它们的引用(子代理的可选模型、压缩摘要模型),每个条目只写一次 profile。这是移除插件之前的一步:插件安装期间这些模型由它服务,所以移除它们会让它们离开输入区。一个平面移除后若不再声明任何模型,就会提供它的整个目录,和一个从未声明模型的条目一样:插件移除后,那就是 pi 已安装的目录。读不到 pi 的目录时,卡片什么也不列出、什么也不移除,并会在清理一行下方说明。 ## 与 OpenCode Console 同时安装 @@ -417,7 +419,7 @@ OpenCode 官方的 Console 插件(`npx @opencode/console setup deepseek-harnes | `400 MissingSessionID` | 未附带会话请求头 | 确认 `dsh-opencode-patch` 已列入 profile 的 `dsh.profile.bundles` | | Auto Review 报 `TRANSPORT: Connection error` | 更新后宿主进程未重启 | 停止并重启 `dsh web`,让新的 `lib/index.mjs` 加载 | | Go 模型始终不显示额度环 | **重启 `dsh web`,然后查看浏览器控制台**——插件通过 `link:` 加载,`lib/index.mjs` 只在进程启动时读取一次,仅刷新页面仍运行旧的宿主代码;计量会报告它的哪条路径没有返回 | 控制台会指出原因:`no remote to mount on`、带异常的 `did not mount`、`still waiting for remote.opencodeGoUsage`、列出其实际暴露键的 `no opencodeGoUsage service on the remote`,或带返回内容的 `the answer is not a usage shape`。缺失或无法路由的凭据只是几个原因之一:在 `opencode-go` 条目上写明 `apiKeyEnv: OPENCODE_GO_API_KEY` 并在 DSH Credentials 中存储该密钥 | -| 目录中的模型在 Settings → Fetch 里缺失,或已下线的模型仍然存在 | 宿主模块过期、补全关闭、该路由不是插件服务的平面(只有所服务的 `llm-pi-ai` 行上的 `opencode`/`opencode-go` 会被补全,留给其他插件(如 OpenCode Console)的路由从不补全),或目录尚未读取(离线,或 `models.opencode.ai` 被拦截)——此时 pi 自己的列表(包括已下线的 id)原样通过,比随包目录更新的模型也不会出现 | `pnpm run build`、重启 `dsh web`、保持**用 OpenCode 官方目录补全列表**开启、从匹配的路由获取、搜索精确 id(如 `gpt-5.3-codex-spark`);目录尚未读取时,待 `models.opencode.ai` 可访问后,先获取一次以触发目录刷新(这次仍是旧列表——刷新在读取之后于后台进行,且没有定时刷新),稍后再获取一次 | +| 目录中的模型在 Settings → Fetch 里缺失,或已下线的模型仍然存在 | 宿主模块过期、补全关闭、该路由不是插件服务的平面(只有所服务的 `llm-pi-ai` 行上的 `opencode`/`opencode-go` 会被补全,留给其他插件(如 OpenCode Console)的路由从不补全),或目录尚未读取(离线,或 `models.opencode.ai` 被拦截)——此时 pi 自己的列表原样通过(随包目录自身记录为已下线的 id 除外),比随包目录更新的模型也不会出现(卡片会在清理一行下方显示上次刷新的错误) | `pnpm run build`、重启 `dsh web`、保持**用 OpenCode 官方目录补全列表**开启、从匹配的路由获取、搜索精确 id(如 `gpt-5.3-codex-spark`);目录尚未读取时,待 `models.opencode.ai` 可访问后,先获取一次以触发目录刷新(这次仍是旧列表——刷新在读取之后于后台进行,且没有定时刷新),稍后再获取一次 | | 弹出面板以红色显示“已达限额” | 滚动 / 每月窗口已用到 100% | 打开 [OpenCode 控制台](https://opencode.ai/console)并启用 _使用余额(Use balance)_,以溢出到 Zen 额度 | | 非 OpenCode 模型行为异常 | 与本补丁无关 | 发往其他网关的流量原样通过 | @@ -444,6 +446,7 @@ OpenCode 官方的 Console 插件(`npx @opencode/console setup deepseek-harnes - **网关的拒绝如实报告。** 在本插件服务的平面上,`FreeTierError`(403)或 `FreeUsageLimitError`(429)现在以 `FREE_TIER` 结束回合,`RegionError`、`ModelDeprecated` 或 `ModelProtocolUnsupported` 以 `MODEL_UNAVAILABLE` 结束,各自带有网关的原话,以及它的状态码(Google 协议的模型除外,其失败文本不带状态码)。过去对话对这些 403 显示“API 密钥无效”(API key is invalid),对用量上限显示“当前请求的额度已用尽”(Request quota exhausted.),网关的消息被丢弃。与被替换的代码一样,这两个新代码都不在宿主的可重试集合中,所以被拒绝的回合仍不会被重发。没有自带工具的免费 Chat Completions 回合现在在免费层的 `read` 与 `bash` 之外带上 `tool_choice: none`,以空 schema 声明的 `read` 或 `bash` 会被完整的定义替换。 - **请求上的密钥只从插件自己的回合中保留,被拒绝两次后丢弃。** 过去插件会记录它认领的每个请求的密钥(包括任何回合之外的请求),并把最近一个回放到任意由配置的提供方认领的请求上;现在它只记录它补齐过的回合中请求的密钥,不在任一平面上的请求只用它自己的路由发往那里的密钥来填补,这样的中继密钥也从不用来填补网关请求或提供给用量计量(名为 `opencode` 或 `opencode-go` 的路由例外:即使它自己的 `baseURL` 指向别处,它的密钥也算作该平面的密钥,就像镜像那样),并且在网关于同一平面上连续两次拒绝某个已捕获的密钥后将其丢弃,只计算它自己回合中的请求:这些回合之外的请求(包括用量计量自己的轮询)从不计入对某个密钥的拒绝。导出的空白密钥或安装存储中的占位值不再作为凭据发出,空白或占位的 `OPENCODE_API_KEY` 也不再被当作计量浮层可用的 Zen 余额。以任意顺序停用两个相互重叠的激活,现在都会留下它们之前就在的那个 `fetch`。 - **平面的请求头按调用设置,其他插件的 `llm-pi-ai/request-headers` 贡献者也在其上运行。** 在本插件服务的平面上,它的会话、来源与项目请求头通过 `llm-pi-ai` 的按调用请求头接口写入,与 `llm-pi-ai` 自己的路由写入方式相同;其他插件对该接口的贡献者现在也在这些平面上运行:抛出异常的贡献者会以 `REQUEST_HEADERS` 让回合失败,就像它在 `llm-pi-ai` 的路由上本来就会做的那样。该接口最早随 harness `0.2.2-alpha.3` 与 `0.2.2-rc.1` 发布。受支持的范围不变:在较早的宿主上(`0.2.2-alpha.2` 或 `0.2.1` 的构建),插件自己的请求头照样发出,仍由它的 fetch 补丁写入;其他插件的贡献者则不会在这些平面上运行,因为这样的宿主从不调用它们(见下文该接口的最低版本)。 +- **清理对每个条目只写一次,按它自己读取的目录来判断,卡片还会列出 `llm-pi-ai` 无法提供的模型。** 过去清理可能对一个条目编辑两次(先是声明,再是引用),并且会重写每个声明了平面的条目,无论有没有已下架的模型;现在没有已下架模型的条目不被触碰,有的只写一次。目录刷新现在会替换它带有模型的每个平面,所以注册表不再列出或已下架的模型在那次刷新时就离开目录,而不是一直留到重启;读取失败或为空时什么也不改变。在清理一行下方,卡片显示目录上次刷新的错误,并列出 pi 无法提供的已声明 id 以及**移除**操作(见[移除或停用插件](#移除或停用插件))。 - **用量设置在插件再次应用时生效,停用插件会撤下它的服务。** 修改 `usageBaseURL`、`keySource` 或 `readOpencodeStore`,或关闭 `usageEnabled`,在插件下一次被应用时生效:即停用后再启用,或 `dsh` 重启时。以前用量服务会一直沿用启动时的值,直到 `dsh` 重启,期间无论停用再启用多少次都不变。停用插件现在会撤下它的用量、清理与存储检查服务,而不是让它们继续应答。 ## 📜 兼容性与验证 diff --git a/docs/deep-dive.md b/docs/deep-dive.md index 4d8f9ca..021288f 100644 --- a/docs/deep-dive.md +++ b/docs/deep-dive.md @@ -170,9 +170,9 @@ How does this compare to Duskriver's [`dsh-opencode-go`](https://www.npmjs.com/p OpenCode's gateway `GET …/models` endpoints frequently return a truncated subset: no display names, context windows, max tokens or input modalities. The plugin ships a **stale-while-revalidate** catalog for both planes: 1. Dual bundled shims (zero latency, offline): `OPENCODE_GO_CATALOG` carries every active Go subscription model with per-million-token rates, so session pricing works before the first refresh; `OPENCODE_ZEN_CATALOG` carries the flagships (`claude-sonnet-4-5`, `claude-opus-4-7`, `gpt-5.4`, `gemini-3.8-flash`, `qwen3.8-max`, `kimi-k3`). The counts are deliberately not restated here: they move with the vendor, they are visible in the generated file, and CI checks the shim for drift: a pull request that changes the generator (or what it loads) fails on a stale shim; any other pull request, and a push to main, warns, and the nightly run proposes the refresh. Retired models are excluded so a failed refresh can never resurrect a row the gateway no longer serves: a retired model is a row the registry marks `status: "deprecated"`, the generator drops it per plane, and, like the counts, the ids are deliberately not restated here. Startup is instant: no cold-start delay, blocking network calls, or airplane-mode failures. -2. Background revalidation: both catalogs revalidate against [`https://models.opencode.ai/api.json`](https://models.opencode.ai/api.json) — the OpenCode catalog, which today serves the byte-identical object as `models.dev/api.json` — every **60 minutes** (the OpenCode CLI's canonical cycle), merging new models, deprecations and updated limits. Errors degrade gracefully and retain the active catalog. +2. Background revalidation: both catalogs revalidate against [`https://models.opencode.ai/api.json`](https://models.opencode.ai/api.json) — the OpenCode catalog, which today serves the byte-identical object as `models.dev/api.json` — every **60 minutes** (the OpenCode CLI's canonical cycle). Each plane the answer carries an active row for is replaced whole, its rows and its retired ids both from that answer, so a model the registry stops listing or retires leaves the catalog on that read; a failed, empty or retired-only answer replaces nothing and keeps the active catalog, and the card names the last read's error under the purge row. 3. Gateway models-endpoint enrichment: `patchFetch` intercepts `GET …/models` on OpenCode routes and merges the live Go or Zen catalog: human-friendly names (`DeepSeek V4.1 Flash 1017`, `Qwen3.8 Flash`, `Grok 4.7`, `MiMo V2.6 Pro`), the catalog's context windows and max output tokens, correct input modalities (`text`, `image`), with registry-deprecated rows omitted. -4. Settings “Fetch Available Models” (`discoverModels`): Settings asks the namespace a provider is configured under — pi-ai's, for both planes — and pi-ai answers a plane from pi's packaged catalog without calling the gateway. On a plane the plugin serves (`opencode`/`opencode-go`, asked on the served `llm-pi-ai` row while the route claim has engaged — not after a stand-down, nor once a served row's restart has settled still holding a plane, a call shape the claim's listener does not speak; the claim reads engaged while the mount's or a handover's restart is in flight), the plugin's wrapper keeps pi's rows and order — rows the OpenCode catalog has retired removed once a live catalog read has landed (offline, pi's list passes through), and each row's fields read from the catalog first and from pi only where the catalog has none, which is the composer's own order (D17), so a row adopted from the fetch carries what the composer already serves rather than pi's older capacities — and appends every servable, non-deprecated catalog model pi lacks, each id once, in the Remote's row shape (`id`, `name`, `contextWindow`, `maxTokens`, `inputModalities`; nothing else, and nothing `undefined`). While pi-ai restarts — the mount's restart or a handover's — its discovery is withdrawn and the host answers `NO_DISCOVERY`; the wrapper answers the plane's catalog alone instead. Nothing is written until the user adopts a row and saves (D8), and the composer still shows the declared list, or the plane's catalog for an entry that declares none. A plane entry another plugin owns — the route claim stepped aside for it (D27): pi-ai's row resolves `credentials` in a realm the plugin's row does not share, or its headers carry `x-opencode-plugin` — is pi-ai's alone: the wrapper answers pi-ai's list untouched, with no catalog complement, and passes pi-ai's `NO_DISCOVERY` through as pi-ai answers it. So is a plane route the served row does not declare yet when that row is in such a realm (the draft Settings opens to add one): the claim would not take it once saved, and pi-ai refuses at save an id it does not list. A route the plugin does not serve — another pi-ai row's planes, a custom relay, a draft whose base is an OpenCode gateway — keeps the enrich-only merge (pi's values first, the catalog filling only what a row omits): pi-ai serves those, and it cannot serve an id it does not list. The gateway-listing enrichment and this wrapper both sit behind the **Enrich listings from the OpenCode catalog** switch (`enrichModels`). The model info a plane answers is not a decoration: the plane adapter builds every model from the user's row and the catalog (D1, D17), whatever the switch says. +4. Settings “Fetch Available Models” (`discoverModels`): Settings asks the namespace a provider is configured under — pi-ai's, for both planes — and pi-ai answers a plane from pi's packaged catalog without calling the gateway. On a plane the plugin serves (`opencode`/`opencode-go`, asked on the served `llm-pi-ai` row while the route claim has engaged — not after a stand-down, nor once a served row's restart has settled still holding a plane, a call shape the claim's listener does not speak; the claim reads engaged while the mount's or a handover's restart is in flight), the plugin's wrapper keeps pi's rows and order, less the rows the OpenCode catalog has retired: the bundled catalog's own retirements until a read lands, and that read's after, so offline pi's list passes through less the bundled retirements. Each row's fields read from the catalog first and from pi only where the catalog has none, which is the composer's own order (D17), so a row adopted from the fetch carries what the composer already serves rather than pi's older capacities. The wrapper then appends every servable, non-deprecated catalog model pi lacks, each id once, in the Remote's row shape (`id`, `name`, `contextWindow`, `maxTokens`, `inputModalities`; nothing else, and nothing `undefined`). While pi-ai restarts — the mount's restart or a handover's — its discovery is withdrawn and the host answers `NO_DISCOVERY`; the wrapper answers the plane's catalog alone instead. Nothing is written until the user adopts a row and saves (D8), and the composer still shows the declared list, or the plane's catalog for an entry that declares none. A plane entry another plugin owns — the route claim stepped aside for it (D27): pi-ai's row resolves `credentials` in a realm the plugin's row does not share, or its headers carry `x-opencode-plugin` — is pi-ai's alone: the wrapper answers pi-ai's list untouched, with no catalog complement, and passes pi-ai's `NO_DISCOVERY` through as pi-ai answers it. So is a plane route the served row does not declare yet when that row is in such a realm (the draft Settings opens to add one): the claim would not take it once saved, and pi-ai refuses at save an id it does not list. A route the plugin does not serve — another pi-ai row's planes, a custom relay, a draft whose base is an OpenCode gateway — keeps the enrich-only merge (pi's values first, the catalog filling only what a row omits): pi-ai serves those, and it cannot serve an id it does not list. The gateway-listing enrichment and this wrapper both sit behind the **Enrich listings from the OpenCode catalog** switch (`enrichModels`). The model info a plane answers is not a decoration: the plane adapter builds every model from the user's row and the catalog (D1, D17), whatever the switch says. ### 8. Session spend & model rate diff --git a/docs/improvement-plan.md b/docs/improvement-plan.md index a8f7bcc..85c7098 100644 --- a/docs/improvement-plan.md +++ b/docs/improvement-plan.md @@ -40,7 +40,7 @@ Phases land as **stacked pull requests**. The open ones are rebased, each onto i | P8 | | `fix:` the card says when its settings apply, over one settings table | in review | **on P7**; one field table (`src/settings-table.ts`: `SETTINGS`, a row per key, and `SETTING_PROSE`, its host-only prose) from which `config.ts` derives the schema, resolver, types, defaults and config-only list, `settings-fields.ts` the card specs, and `settings-copy.ts` checks the copy keys; `cordis.patch.yml`'s header held to it by order, type label, stated default and choice values; fifteen dead copy keys and the meter's `modelMarkers` prop deleted, the zh README's stale name for the card replaced by the package's `meta.title`, and the card says its settings apply on re-apply (performed on the real host in both channels: a volatile edit of the plugin's row commits in place and the plugin follows it only once re-applied). No setting changed: the schema, resolver and card pins (`test/settings-snapshot.test.ts`) were green on the base and land unchanged but for the named edits (the copy keys, `CONFIG_DEFAULTS`' `credentialOrg: undefined`, the resolved type's modifiers). Retitled from `refactor:` (P-H's, P5's and P6's precedent): under squash the pull request's title is the release signal and a `refactor` is hidden from the changelog, while the phase ships a visible card line and the README pair's re-apply sentence. No `!` and no BREAKING CHANGE footer (1.x minors only); the owner may keep `refactor:` at landing, and the card line then ships without a changelog entry | | P9 | | `refactor:` remote seam | in review | **on P8**; one builder (`defineRemote`, `src/contracts/remote.ts`) derives every descriptor and codec of the three contracts, which move into `src/contracts/` with `REMOTE_CONTRACTS` the one list the client mounts; `markRemote` writes each service's marker from its contract; `callRemote`/`unwrapRemote` are the one unwrap of the four client callers; `isGoUsage` deleted, `USAGE_NAMESPACE` and `parseUsageReading` added; `remote-contract` reads the contracts and the mounted services | | P10a | | `refactor:` pure module moves | in review | **on P9**; the discovery wrapper to `src/host/discovery.ts`; the meter's discovery and key resolution into `src/credentials.ts`; `usage-ui.ts` split into `usage-css.ts`, `usage-time.ts`, `usage-state.ts` and `usage-copy.ts`, with `parseFailure` in `src/contracts/usage.ts`; the fetch patch into stages under `src/request/` (claim, body, credential, headers, and `patch-fetch.ts` composing them), `callHeadersFor` beside the patch's own header stage, and a claimed request's body parsed once; no behaviour changed, and every name the door exports keeps its signature | -| P10b | | `fix:` catalog state | planned | | +| P10b | | `fix:` catalog state and the purge | in review | **on P10a**; the parse is pure and answers each plane's retired ids, and the live catalog is one state per plane (rows and retired ids) seeded from the shim and replaced, never merged, by a refresh that carries an active row for that plane (L12: a failed, empty or retired-only read replaces nothing); `refreshCatalog` resolves `{ ok, deprecated, go, zen }` and keeps its `lastError`, which the card shows beside the purge row (L14, carried from P8); the purge judges by its own read's answer and writes each entry at most once, skipping an entry with nothing retired; the generator emits `OPENCODE_DEPRECATED_IDS` and stale covers the whole generated output through one reader; `src/catalog-data.ts` is read tolerantly until it carries the export, and its regeneration with THIS phase's generator lands with the phase (it is never hand-edited, and the machine the phase was built on cannot reach the registry): the pull request changes the generator, so CI's `catalog freshness` step gates it and stays red until a generator-written shim is committed, which the nightly refresh cannot supply because it runs `main`'s generator; the card lists the declared ids pi cannot serve and removes them (the "Removing the plugin" story), proved on the real host in tier B, a removal's next Settings edit after the handback accepted and its control refused in pi-ai's words; `llm/models-updated` is not emitted (carried) | | P11 | | `refactor:` UI on the primitives | planned | | | P12 | | `ci:` lint warnings gating | planned | | @@ -511,6 +511,13 @@ What stays private is pinned by contract tests against the real host packages: - The parse is pure and returns `deprecated`, and a refresh replaces the maps. - The purge makes one edit per entry. - The card lists the ids pi can't serve, and removes them. + - **As landed.** + - **One state, replaced per plane.** `src/models-catalog.ts` holds `state: Record`, seeded by `shimState()` from the shim's rows and its retired ids, and a refresh replaces a plane only when the payload carries at least one active row for it, its rows and its retired ids both from that payload; a plane it carries none for keeps both (L12). Per plane rather than all-or-nothing: the zen-only registries the purge, discovery and request-path cases seed each land one plane, and the stricter reading would make each of them carry a live row on the other plane. `ok` is "at least one plane landed"; `lastError` is one sentence of at most 200 characters (the thrown message, `models.opencode.ai answered `, `the registry listed no active model for `, or `the registry's answer listed no active model`), cleared by a landing on both planes and by `resetCatalogState`. `didCatalogRefreshSucceed` and its flag are gone: the purge reads its own refresh's `ok`. + - **The tolerant shim read, and why.** The generator writes `OPENCODE_DEPRECATED_IDS` (inserted before `OPENCODE_GO_CATALOG` by `upsertObject` when the file lacks it), but `src/catalog-data.ts` was not regenerated here: the registry is unreachable from the machine this phase ran on, and the file is never hand-edited. Until it carries the export, the runtime reads it off the module namespace (`shippedDeprecatedIds`, `deprecatedIdsOf`) and the scripts through `shippedShim`, absent meaning no retired id; a named import would be a link error. Turning both into named imports is a follow-up once the shim carries the export. + - **The regeneration is a landing step, not a follow-up.** This pull request changes the generator's inputs, so `scripts/freshness-scope.ts` answers `gate` and CI's "is src/catalog-data.ts current?" step fails on it: the generator now compares retired ids, the committed shim has none, and the registry lists deprecated rows. The nightly "propose the refresh" runs only on `schedule`, on `main`, with `main`'s generator, which does not write the export, so it cannot close this gate before the merge. Landing therefore runs `pnpm run catalog:shim -- --write` (or `--from` a fetched `api.json`, which is still generator output) and `vp fmt` with THIS branch's generator where `models.opencode.ai` is reachable, commits the result into the pull request, and re-runs `catalog-refresh`, `models-discovery` and the `S0_TODAY_BY_CELL` discovery rows against it (a pi row the shim retires drops on a cold start). If no such run is possible, the owner accepts the red `catalog freshness` gate on this pull request explicitly. + - **Two new purge methods, no wire change to `purge`.** `review()` answers `{ unserved, piRead, catalogError? }` (no network, no edit) and `removeUnserved()` answers a `PurgeResult` (no catalog read), both zero-argument, beside `purge` in `purgeRemote`. The ids pi cannot serve are judged by `piUnservedIds` (`src/utils/plane-profile.ts`), the mirror of pi-ai's "needs an api" rule over pi's own `getBuiltinModels` (`loadHostLibraries`, the libraries half of the host-module seam); pi unreadable lists nothing and removes nothing. The card reads the review on mount and after each action settles, and shows the removal block only when there is something to remove. + - **From the review.** The removal judges each entry's declarations by that entry's own block (an entry with a route-level `api` keeps an id another entry on the same route cannot serve), and references, which name a route and not an entry, by every owned entry's rows; the review lists an id two entries declare once. Route-wide on purpose: two owned entries on one route conflict in the host's registry (the second registration of a provider is a `DUPLICATE_ADAPTER`), so which one serves the route once the plugin is gone depends on apply order, and a reference cannot be attributed to the entry that keeps the id. `review()` answers the catalog's last error whatever the profile declares: a profile with no plane entry this plugin owns lists nothing, and only a composition with no config editor refuses. The card says when a review could not read pi's catalog, in its own neutral sentence (`unservedPiUnreadReview`), so the README's "says so" holds on mount, not only after a click; `unservedPiUnread` stays the removal's outcome, so the two lines never coincide. Refresh attempts are numbered: a forced refresh does not wait for one in flight, and only the newest attempt writes an error into `lastError` and clears the in-flight promise, so a slow background failure cannot report over the purge's newer success, and a plain call still joins the newer attempt after an older one settles. Any attempt that lands both planes clears `lastError`, because the state is then wholly that payload's, so a newer failure cannot outlive an older success that settled after it. A plane left with no declared model offers its whole catalog (pi's installed one once the plugin is gone), which both READMEs now say; the plugin does not compensate for it (D26). + - **Not done:** emitting `llm/models-updated` on refresh (optional in the restack row; `onCatalogChange` already re-derives the plane profiles), an all-or-nothing landing rule, and regenerating the shim (above: a landing step). 20. **P11 `refactor:` UI on the primitives.** 21. **P12 `ci:`** make lint warnings gating once `src/` is at zero. @@ -551,7 +558,7 @@ How each phase changes now that it sits on `main` 1.8.0 and on both harness chan | P8 | The health snapshot shows the catalog's `lastError` on the card. From P5's review: every field of the row is `.volatile()`, and a Settings edit takes the loader's volatile-only path (`entry.update` → `_commitVolatile`, no remount), while `resolveConfig` unwraps each node once at apply; so no part of the plugin (the usage options, the fetch patch, the stream hook) follows a Settings edit until the plugin is applied again. P8 decides whether the settings table reads those values per call or says in the card that they apply on re-apply. **As landed:** they apply on re-apply, and the card says so once above its controls (`appliesOnReapply`), as both READMEs do; `host-planes` performs it on the real host in both channels (a volatile edit of the plugin's own row, then a re-apply). Reading per call is not a refactor: `lifecycle.ts` mounts the usage service at apply only when `usageEnabled` is on, copies `keySource` and `readOpencodeStore` into the services it builds, and the route claim reads `endpoint` once. The catalog's `lastError` on the card is carried to P10b: no health snapshot exists, `refreshCatalog` swallows its error, and the carrier would be a remote contract that P9 reshapes over catalog state that P10b rewrites. | | P9 | A loopback triple guard, only if a `webServer` route appears. **As landed:** no `webServer` route appeared; nothing built (L14). | | P10a | L1's per-call shaping is the first move of `fetch-patch` into `request/` (landed: `callHeadersFor` is in `request/headers.ts` beside the patch's own header stage). L4, carried from P6 and again from P10a (P-R2 measured nothing, and no keyed variants run was made in P10a): with the next keyed variants run, drop `x-opencode-request` or send it only where it is accepted, which is one line in `planeHeadersFor` and one expectation in `test/host-planes-headers.test.ts`. | -| P10b | L12's test; optionally emit `llm/models-updated` on refresh, a new host event. The catalog's `lastError` on the card (L14), carried from P8: the refresh keeps its last error with the state it rewrites, and the card shows it beside the purge row. | +| P10b | L12's test; optionally emit `llm/models-updated` on refresh, a new host event. The catalog's `lastError` on the card (L14), carried from P8: the refresh keeps its last error with the state it rewrites, and the card shows it beside the purge row. **Done:** L12's test (`catalog-refresh`'s "a failed or empty read replaces nothing, and a partial one replaces only the plane it carries") and the `lastError` on the card. **Carried:** `llm/models-updated`, not emitted. | | P11, P12 | Unchanged. | ## Lessons from opencode2dsh @@ -571,7 +578,7 @@ Two community plugins solve the same problem on the same host: [`FishBottle7/ope | L9 | **Honour `Retry-After`.** dsh-llm accepts `providerRetryAfterMs` and `dsh-llm-pi-ai` never fills it. pi's `onResponse` exposes the headers only after a 2xx (and Google has none), so a refusal's header is visible only at the fetch layer. | SF `lib/errors.js`. | P-R2 records whether Go's 429s carry it; P-R3 fills it | Measured: run 43542273415 answered no keyed 429 (its `Retry-After` line is in §13), so nothing to fill; when one does, at the fetch layer (P6) | | L10 | **Offer Off on plain chat-completions reasoning models** through `reasoning_effort: "none"`; ours offers Off only for a few body formats. | FB `packages/plugin/src/adapter/zen-adapter.ts`; `src/utils/model-metadata.ts`. | P-R2 keyed probe, then P-R1's metadata | Unmeasured: run 43542273415's pair was refused before the field mattered, its control as much as `"none"` (Zen account 403, Go model-gone 410, a retired id); Off stays as P-R1's metadata offers it until a served reasoning completions model answers the pair | | L11 | **Context-window overrides with dated evidence.** FB keeps measured windows for two free models that differ from the catalog's; an understated window is the overflow trap. | FB `packages/plugin/src/adapter/catalog.ts`. | P7 | Adopted in P7 as the pattern only: `MEASURED_CONTEXT_WINDOWS` (`src/utils/context-windows.ts`), each row a window, an ISO date and its evidence, read ahead of the catalog's window by the plane model and the discovery rows; it ships with no rows, since this repository has measured none (FB's two are FB's) | -| L12 | **A failed or partial refresh must not replace the maps.** | SF `lib/catalog.js`; FB `packages/plugin/src/adapter/catalog.ts`. | P10b | Adopt | +| L12 | **A failed or partial refresh must not replace the maps.** | SF `lib/catalog.js`; FB `packages/plugin/src/adapter/catalog.ts`. | P10b | Adopted in P10b, per plane: a failed, empty or retired-only read replaces nothing, and a plane the payload carries no active row for keeps what it had (step 19). A payload that lists fewer active rows for a plane replaces it: a truncated body is invalid JSON and already replaces nothing, and a well-formed shorter list cannot be told from the registry shrinking, so no size guard second-guesses it. | | L13 | **Test against the host's newer pi**, not only the pin: unit and tier A on the newest pi the host's range resolves, not just the binary e2e; the `/zen/v1/systemone` family belongs in P-R2's families. | FB's hoisted-pi test and loader hook. | P-T1a (unit and mock on each channel's newest pi), P-T1b (tiers A and B), P-R2 (the family) | Adopt | | L14 | Smaller: a triple loopback guard if a `webServer` route is ever added (the remotes seam remains the better one); the host's `volatileForm()` as an alternative to hand-written card fields; the catalog's `lastError` on the card rather than in a file. | FB `packages/plugin/src/ip-pool-settings/bridge.ts`, `packages/plugin/src/config.ts`. | P9, P11, P10b | Adopt where the phase reaches it | @@ -814,6 +821,18 @@ The vendor's own first-party DSH plugin, `@opencode/console` 0.1.10 (`anomalyco/ - **Red on the base, landing with the change:** `fetch-patch-tools`' "a claimed request's body is parsed once", run with the body on the init and on a Request (`JSON.parse` of the request's own text or of the text it went out as: 1 call after; the base parsed the original text twice and the rewritten text once more; a control that has the debug names parse the wire text fails both shapes), with its `vi.restoreAllMocks()` in the file's `afterEach`, which only that case's spy needs, `architecture`'s environment rule over `src/request/` (the folder does not exist on the base), `planes`' scans with the allowances keyed to `credentials.ts`, and `keyed-probes`' e2e-host scope case (the base's pattern does not match `src/request/patch-fetch.ts`). - **Test edits that are not pins, path literals only:** `architecture`, `planes`, `keyed-probes` and `usage-pill-mount` (above, "As landed"); the door's blocks; comment-only edits in `host-tokens`, `tool-fallback` (its header names `request/body.ts`'s `maybeInjectCoreTools` and `withSentBody`'s reference check) and `test/support`. +**P10b** + +- **Red on the base (`fcf56ee`), no src edit, each by its failing assertion:** `catalog-refresh` (the malformed-data literal gains `deprecated` and fails on the base's four keys; the replace case answers the shim's 35 Go ids where `["only-go"]` was expected, rewriting the merge case that pinned `OPENCODE_GO_CATALOG.length + 1`; "a parse moves nothing" reads the retirement cleared by a second parse; "the parse answers the retired ids" reads `undefined`; L12's case and the `{ ok, deprecated }` case read `ok` as `undefined`; the retire-one-shipped-id and shim-retirements cases name functions the base lacks), `purge-service` (one edit per entry: 2 calls where 1 was expected; an entry with nothing retired: edited once; a parse while the purge runs: nothing removed; `purgeEntryConfig`, `review` and `removeUnserved` absent), `generators` (the parse carries no `deprecated`; the spawned regenerate run over a payload with one made-up retired row exits 0 "shim is current"; `rewriteShim` absent), `plane-profile` (`piUnservedIds` absent), `purge-contract` (`parsePurgeReview` absent), `settings-purge` (`reviewPurge`, `removeUnservedModels` absent), `settings-card-purge` (`reviewLines`, `unservedLine` absent; the mounted block renders no id list), `remote-contract` (the descriptor table and the purge marker carry one method where three are pinned). +- **Pin, green on the base and kept:** `purge-service`'s "a read that fails is judged by what the process already holds, and says the catalog was not read". +- **Flipped pins:** `purge-service`'s "does not rewrite an entry with nothing to strip" (1 edit to 0) and "writes nothing when the deployment declares no retired model" (now also `edit` not called); `catalog-refresh`'s merge case, rewritten as the replace case. +- **Edited seeds and fixtures, no expectation changed:** `purge-service` drops its twelve `parseModelsDevCatalog` seeds (the purge judges by its own read), its split registry gives Go a live row beside the retired one, its offline case declares a made-up id, and "reports nothing when the edit was rejected" declares a retired id so the edit is still made; `remote-seam` drops its parse seed; `models-discovery`'s retired-adapter-row case seeds through the refresh and its complement case through `registryOf` (the shipped Zen world, one id retired, one row added); `host-planes-foreign`'s `retiringRegistry` and `retireModel` answer `registryOf(shipped, …)`, since a payload of retired rows alone lands no plane; `generators`' `SHIPPED` is `shippedShimData()` and its local `shimPayload` moved to `test/support/catalogs.ts` as `registryOf`; `settings-snapshot`'s copy-key list gains the nine new keys (104 to 113). +- **New with the change:** the tier-B case in `host-planes-config` (the review lists a catalog-unknown id, `removeUnserved` removes it in one config-editor write, the listing drops it, and after the plugin's row is disabled the next Settings edit of `opencode` is accepted; its control, with no removal, is refused with pi-ai's "needs an api"), on both channels; `catalog-refresh`'s TTL and non-Error cases; `purge-service`'s reload-between-judgement-and-write case, a throwing pi read, and an owned route whose block is not a record. +- **From the review, each red under the control named:** `purge-service`'s "removeUnserved judges each entry's declarations by its own block, and review lists an id two entries declare once" (control: one route-wide declaration judge, no dedupe) and "review answers the catalog's last error when no plane entry is the plugin's, and lists nothing" (control: `review` through `ownership` again), with the unit pi stub keyed by route and the routes it was asked recorded (control: every lookup under `opencode` fails the review case and the D27 removal case); "a shim that carries retired ids seeds a cold start with them, and an offline purge removes them" (`vi.doMock` of the shim's export after `vi.resetModules()`; controls: `shimState` dropping the Go seed, the runtime reader looking up another export name); `catalog-refresh`'s "an older attempt that fails after a newer forced one landed leaves no error behind" (control: every attempt writes `lastError`); `generators`' round trip through `rewriteShim` (the committed file plus the inserted block, exactly once the shim carries it), the fixture case asserting the plane and family endpoints and the Go row's catalog and rewriting the FORMATTED text (controls: the family splice dropped, Zen rendered into the Go anchor), and a spawned `--write --from` on a scratch copy that then reads current and answers the id through `shippedDeprecatedIds` (same controls); `settings-page`'s three purge callbacks each reaching only their own host method (control: the review wired to the removal); `settings-card-purge`'s re-read showing the second answer, the purge-click re-read, the fresh-closure re-render, a stale answer dropped and the pi-unread caption (controls: the caption removed, the `live` guard bypassed, the closure in the effect's dependencies). +- **From the second review, each red under the control named:** `catalog-refresh`'s "an older attempt that lands both planes after a newer failure clears the error" (flipped from the pin that kept the newer 503 beside a landed catalog; control: only the newest attempt clears `lastError`) and "an older attempt that settles first leaves the newer one in flight, and a plain call joins it" (control: every attempt clears the in-flight promise; the earlier case's TTL answer could not show it); green on both: "an older attempt that lands one plane after a newer failure leaves the newer error". `settings-card-purge`'s mount caption reads the neutral review sentence (`unservedPiUnreadReview`), and a removal that could not read pi followed by a review that could not either shows each sentence once; `settings-purge` pins the invalid review's sentence exactly. +- **Tightened from the review, green on the change:** `host-planes-config`'s tier-B review and removal are exact (`[{ id: UNSERVED, provider: "opencode" }]`) and the written patch still declares `deepseek-v4-pro`, read with the YAML parser; `catalog-refresh`'s 200-character cap is `"x".repeat(200)`, L12's loop asserts each failure's message, its world carries a Go retirement so a partial landing's `deprecated` shows the held plane, and the TTL case states why it answers `ok`; `generators`' `shippedShim` read with the export present, in another order and malformed; `remote-seam` joins `review` and `removeUnserved` to `reviewPurge` and `removeUnservedModels`; `settings-purge` names the removal's absent service, refusal and invalid answer; `test/support/catalogs.ts`' `registryOf` throws on a family nothing carries instead of inventing a retired row, with a `generators` case for it. +- **Measured:** `lib/client.js` 156,038 bytes, from 146,953 on the base; `CLIENT_BUDGET` raised 146 -> 155 KB with its history paragraph (source and comments, no dependency, no catalog row in the client). + ## End-to-end infrastructure ### The `e2e-host` job (`ci.yml`) diff --git a/docs/testing.md b/docs/testing.md index 93c57c5..ede8b92 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -67,7 +67,8 @@ Properties the unit and mock suites keep by construction rather than by care: `test/support/catalogs.ts` — **catalogue rows**, reaching `src` through the one door like the other fixtures. It does two things. It picks rows of the SHIPPED shim by shape (`findCatalogRow`, `catalogRow`, `freeZenModel`), so a case about "a Messages model on Go" never names one. And it builds the rows a test needs, including rows the vendor has not produced: the plane-aware decisions are only observable when the two planes DISAGREE, and the real catalogue agrees about the free flag for every model it shares. - `spec(...)` / `divergent(id, { go, zen })` build a row (or a pair of rows) directly, for a decision that takes the row as its parameter — `coreToolDecision`, `calculateTurnCost`. -- `payload({ go, zen })` builds a whole `models.dev` payload, for the paths that read the LIVE catalogue through `refreshCatalog` (`test/plane-lookup.test.ts`, the plane price and the plane-lookup fallback in `test/stream-hook.test.ts` and `test/fetch-patch.test.ts`). That world is per TEST: `refreshCatalog` merges by id and cannot remove, but the setup file resets the live catalog after every test, so a case installs its world itself and gives its rows ids no other test names. +- `payload({ go, zen })` builds a whole `models.dev` payload, for the paths that read the LIVE catalogue through `refreshCatalog` (`test/plane-lookup.test.ts`, the plane price and the plane-lookup fallback in `test/stream-hook.test.ts` and `test/fetch-patch.test.ts`). That world is per TEST: `refreshCatalog` replaces each plane the payload carries an active row for (a plane it carries none for keeps what it had), and the setup file resets the live catalog after every test, so a case installs its world itself, carries every row it reads on a plane it seeds, and gives its rows ids no other test names. +- `registryOf(data, { retire, add })` builds the payload that reproduces a shim (`shippedShimData()` for the shipped one), with ids moved to `status: "deprecated"` and rows added: the generator's "current" cases, and a case that retires one shipped id while keeping the rest of the plane. - `seedDivergentCatalog()` installs one such world for the request-path tests: `ZEN_FREE_PROBE` is free on Zen and paid on Go, `GO_FREE_PROBE` the reverse, so a lookup that reads the wrong plane is red in both directions (`test/tool-fallback.test.ts`, `test/fetch-patch-headers.test.ts`). **A model with no price in a fixture is PAID at a nominal rate, not free.** The parser derives `is_free` from a zero cost, so a "no price" default would silently turn every fixture model into a free tier. diff --git a/scripts/catalog-shim.ts b/scripts/catalog-shim.ts index d473671..4d55005 100644 --- a/scripts/catalog-shim.ts +++ b/scripts/catalog-shim.ts @@ -4,11 +4,14 @@ * whether the shipped shim is stale against it. * * Every export the generator writes counts: the two catalogs, the plane - * endpoints (`OPENCODE_PLANE_API`) and the family endpoints - * (`OPENCODE_FAMILY_API`). The generator used to compare only the catalogs, - * so a vendor that moved an endpoint left the shim reporting "current" while - * the mount read the old address. `verify-catalog.ts` asks the same question - * through `shimStale`, so the two can never disagree about it. + * endpoints (`OPENCODE_PLANE_API`), the family endpoints + * (`OPENCODE_FAMILY_API`) and the retired ids (`OPENCODE_DEPRECATED_IDS`). + * The generator used to compare only the catalogs, so a vendor that moved an + * endpoint left the shim reporting "current" while the mount read the old + * address. `verify-catalog.ts` asks the same question through `shimStale`, + * and both read what the file exports through one function (`shippedShim`), + * so the two can never disagree about it. The whole generated output is one + * function too (`rewriteShim`), which the script and its tests share. * * @module scripts/catalog-shim */ @@ -18,8 +21,12 @@ import { stale } from "./generator-kit.ts"; /** One plane's endpoint per SDK package (`""` is the provider's default). */ type FamilyApi = Readonly>; -/** The four values the shim carries, in the shape `shimStale` compares. */ +/** The retired ids per plane, as the shim carries them. */ +type DeprecatedIds = Readonly>; + +/** The five values the shim carries, in the shape `shimStale` compares. */ export interface ShimData { + readonly deprecated: DeprecatedIds; readonly familyApi: Readonly>; readonly go: readonly CatalogModelSpec[]; readonly planeApi: Readonly>; @@ -29,6 +36,7 @@ export interface ShimData { /** What `parseModelsDevCatalog` answers, read-only. */ export interface ParsedShim { readonly api: Readonly>; + readonly deprecated: DeprecatedIds; readonly familyApi: Readonly>; readonly go: readonly CatalogModelSpec[]; readonly zen: readonly CatalogModelSpec[]; @@ -41,13 +49,21 @@ const TARGET = "catalog-data.ts"; const byId = (specs: readonly CatalogModelSpec[]): CatalogModelSpec[] => specs.toSorted((a, b) => a.id.localeCompare(b.id)); +/** Each plane's retired ids, sorted: their order is not data. */ +const sortedIds = (deprecated: DeprecatedIds): DeprecatedIds => ({ + go: deprecated.go.toSorted(), + zen: deprecated.zen.toSorted(), +}); + /** * What a parsed payload makes of the shim. * * @param parsed - `parseModelsDevCatalog`'s answer. - * @returns the four values, each catalog sorted by id. + * @returns the five values, each catalog sorted by id and each retired list + * sorted. */ export const shimData = (parsed: ParsedShim): ShimData => ({ + deprecated: sortedIds(parsed.deprecated), familyApi: parsed.familyApi, go: byId(parsed.go), planeApi: parsed.api, @@ -56,19 +72,66 @@ export const shimData = (parsed: ParsedShim): ShimData => ({ /** * Whether the shipped shim is stale against `next`: the one rule - * (`generator-kit.ts`'s `stale`) over all four values. Row order is the - * renderer's, so both sides are sorted by id first. + * (`generator-kit.ts`'s `stale`) over all five values. Row order is the + * renderer's and retired-id order is not data, so both sides are sorted first. * - * @param shipped - what `src/catalog-data.ts` exports. + * @param shipped - what `src/catalog-data.ts` exports (`shippedShim`). * @param next - what the source makes of it today (`shimData`). - * @returns whether any of the four differs in data. + * @returns whether any of the five differs in data. */ export const shimStale = (shipped: ShimData, next: ShimData): boolean => stale( - { ...shipped, go: byId(shipped.go), zen: byId(shipped.zen) }, - { ...next, go: byId(next.go), zen: byId(next.zen) } + { + ...shipped, + deprecated: sortedIds(shipped.deprecated), + go: byId(shipped.go), + zen: byId(shipped.zen), + }, + { + ...next, + deprecated: sortedIds(next.deprecated), + go: byId(next.go), + zen: byId(next.zen), + } ); +/** One plane's retired ids from an exported value; anything else is none. */ +const idList = (value: unknown): readonly string[] => + Array.isArray(value) + ? value.filter((id): id is string => typeof id === "string") + : []; + +/** + * What the generated file exports, by name, in the shape `shimStale` + * compares: the one reader of `src/catalog-data.ts` both scripts use, so a + * new export is added in one place. An absent or malformed + * `OPENCODE_DEPRECATED_IDS` (a shim generated before it existed) reads as no + * retired id on either plane. + * + * @param exports - the module namespace of `src/catalog-data.ts`. + * @returns the five values. + */ +export const shippedShim = ( + exports: Readonly> +): ShimData => { + const deprecated: unknown = exports.OPENCODE_DEPRECATED_IDS; + const record = + typeof deprecated === "object" && deprecated !== null + ? (deprecated as Readonly>) + : {}; + return { + deprecated: { go: idList(record.go), zen: idList(record.zen) }, + // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the generated file's own exports, named by the declarations it writes. + familyApi: exports.OPENCODE_FAMILY_API as ShimData["familyApi"], + // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- as above. + go: exports.OPENCODE_GO_CATALOG as ShimData["go"], + // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- as above. + planeApi: exports.OPENCODE_PLANE_API as ShimData["planeApi"], + // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- as above. + zen: exports.OPENCODE_ZEN_CATALOG as ShimData["zen"], + }; +}; + /** Thousands separators, matching how the file already reads. */ const numeral = (value: number): string => String(value).replaceAll(/\B(?=(\d{3})+(?!\d))/gu, "_"); @@ -185,3 +248,89 @@ export const renderFamilyApi = ( go: ${JSON.stringify(familyApi.go)}, zen: ${JSON.stringify(familyApi.zen)}, }`; + +/** + * The retired ids each plane's registry lists, as the shim carries them. + * + * Emitted so a cold or offline start knows what the registry had retired when + * the shim was generated: pi's installed snapshot still lists such ids, and + * without them the discovery merge would offer them until the first refresh. + */ +export const renderDeprecated = (deprecated: DeprecatedIds): string => + `{ + go: ${JSON.stringify(deprecated.go)}, + zen: ${JSON.stringify(deprecated.zen)}, +}`; + +/** + * {@link spliceObject} when the `export const NAME: ` anchor exists; otherwise + * insert `declaration` immediately before the `export const BEFORE` anchor, so + * a shim generated before an export existed gains it from a `--write`, with no + * hand edit. + * + * @param source - the file's text. + * @param name - the export to replace or add. + * @param declaration - the whole declaration to insert, blank line included. + * @param body - the object literal to splice when the export exists. + * @param before - the export the new declaration goes in front of. + * @returns the rewritten text. + */ +export const upsertObject = ( + source: string, + name: string, + declaration: string, + body: string, + before: string +): string => { + if (source.includes(`export const ${name}: `)) { + return spliceObject(source, name, body); + } + const anchor = source.indexOf(`export const ${before}`); + if (anchor === -1) { + throw new Error(`could not find ${before} in ${TARGET}`); + } + return `${source.slice(0, anchor)}${declaration}${source.slice(anchor)}`; +}; + +/** The retired-ids declaration, as a shim without one gains it. */ +const deprecatedDeclaration = (deprecated: DeprecatedIds): string => + `/** + * The ids each plane's registry lists as \`status: "deprecated"\`, sorted: what + * a cold or offline start holds as retired until the first refresh lands. + */ +export const OPENCODE_DEPRECATED_IDS: Readonly< + Record<"go" | "zen", readonly string[]> +> = ${renderDeprecated(deprecated)}; + +`; + +/** + * The whole generated output: `source` with every value the generator owns + * replaced by `data`'s, the retired ids added in front of the Go catalog when + * the file does not carry them yet. + * + * @param source - `src/catalog-data.ts` as it stands. + * @param data - what the source makes of it today (`shimData`). + * @returns the text `--write` writes, before the formatter. + */ +export const rewriteShim = (source: string, data: ShimData): string => { + let next = splice(source, "OPENCODE_GO_CATALOG", render(data.go)); + next = splice(next, "OPENCODE_ZEN_CATALOG", render(data.zen)); + next = spliceObject( + next, + "OPENCODE_PLANE_API", + renderPlaneApi(data.planeApi) + ); + next = spliceObject( + next, + "OPENCODE_FAMILY_API", + renderFamilyApi(data.familyApi) + ); + return upsertObject( + next, + "OPENCODE_DEPRECATED_IDS", + deprecatedDeclaration(data.deprecated), + renderDeprecated(data.deprecated), + "OPENCODE_GO_CATALOG" + ); +}; diff --git a/scripts/check.ts b/scripts/check.ts index f66c946..1706d63 100644 --- a/scripts/check.ts +++ b/scripts/check.ts @@ -363,8 +363,19 @@ try { * 146953 bytes against the old line, from 143074 on the base. 146 rather * than 144 keeps the ~3 KB of room this line is meant to have; at 144 the * bundle sat under a kilobyte below it. + * + * Raised 146 -> 155 KB when P10b gave the purge row its review: the card now + * lists the declared ids pi cannot serve and removes them on request (the + * review block and its two pure line builders in `src/settings-card.tsx`), the + * client carries the review's whitelist parser and two more methods in the + * purge contract (`src/contracts/purge.ts`), the three purge calls share one + * outcome mapper (`src/settings-purge.ts`), and nine copy keys arrive in + * both languages. Source and its comments, not a dependency (the bundle still + * requires only react and the UI primitives, and no catalog row reaches it) — + * the client measured 156038 bytes against the old line, from 146953 on the + * base. 155 keeps about 2.6 KB of the ~3 KB of room this line is meant to have. */ -const CLIENT_BUDGET = 146 * 1024; +const CLIENT_BUDGET = 155 * 1024; const clientPath = join(ROOT, "lib/client.js"); if (existsSync(clientPath)) { const clientStat = statSync(clientPath); diff --git a/scripts/regenerate-catalog-shim.ts b/scripts/regenerate-catalog-shim.ts index 02a78a2..3a3746e 100644 --- a/scripts/regenerate-catalog-shim.ts +++ b/scripts/regenerate-catalog-shim.ts @@ -1,5 +1,6 @@ /** - * Regenerate `src/catalog-data.ts`'s two catalogs from models.dev. + * Regenerate `src/catalog-data.ts` from models.dev: its two catalogs, the + * plane and family endpoints, and the ids each plane has retired. * * The shim is the catalog DSH sees **before the first successful refresh** — and * if a refresh never succeeds. That makes it load-bearing in a way a normal @@ -20,21 +21,17 @@ * * Without `--write` it only reports what would change, so it is safe to run in CI * or by hand to answer "is the shim stale?". Stale is decided by the one rule - * the generators share (`generator-kit.ts`) over everything the file exports: - * both catalogs, the plane endpoints and the family endpoints - * (`catalog-shim.ts`, the pure half). With `--write`, a current shim is left - * untouched. + * the generators share (`generator-kit.ts`) over everything the file exports, + * read through one function (`shippedShim`): both catalogs, the plane + * endpoints, the family endpoints and the retired ids (`catalog-shim.ts`, the + * pure half). With `--write`, a current shim is left untouched, and a shim + * that predates the retired ids gains their export (`rewriteShim`). */ import { readFileSync, writeFileSync } from "node:fs"; import { basename } from "node:path"; -import { - OPENCODE_FAMILY_API, - OPENCODE_GO_CATALOG, - OPENCODE_PLANE_API, - OPENCODE_ZEN_CATALOG, -} from "../src/catalog-data.ts"; +import * as shipped from "../src/catalog-data.ts"; import { type CatalogModelSpec, MODELS_DEV_TIMEOUT_MS, @@ -42,13 +39,10 @@ import { parseModelsDevCatalog, } from "../src/models-catalog.ts"; import { - render, - renderFamilyApi, - renderPlaneApi, + rewriteShim, shimData, shimStale, - splice, - spliceObject, + shippedShim, } from "./catalog-shim.ts"; import { generatorArgs, outcome, readSource } from "./generator-kit.ts"; @@ -61,17 +55,16 @@ const payload = await readSource({ url: MODELS_OPENCODE_URL, }); const next = shimData(parseModelsDevCatalog(JSON.parse(payload))); +const current = shippedShim(shipped); -/** What the shim holds now, for the report. */ +/** What the shim holds now against what it would hold, for the report. */ const report = ( label: string, - before: readonly CatalogModelSpec[], - after: readonly CatalogModelSpec[] + before: readonly string[], + after: readonly string[] ) => { - const ids = (specs: readonly CatalogModelSpec[]) => - new Set(specs.map((s) => s.id)); - const had = ids(before); - const has = ids(after); + const had = new Set(before); + const has = new Set(after); const added = [...has].filter((id) => !had.has(id)); const removed = [...had].filter((id) => !has.has(id)); console.log(`${label}: ${before.length} -> ${after.length}`); @@ -86,37 +79,17 @@ const report = ( console.log( `source: ${fromPath ?? MODELS_OPENCODE_URL} (${payload.length} bytes${fromPath === undefined ? "" : ", local"})` ); -report("opencode-go", OPENCODE_GO_CATALOG, next.go); -report("opencode ", OPENCODE_ZEN_CATALOG, next.zen); +const ids = (specs: readonly CatalogModelSpec[]): string[] => + specs.map((spec) => spec.id); +report("opencode-go", ids(current.go), ids(next.go)); +report("opencode ", ids(current.zen), ids(next.zen)); +report("retired opencode-go", current.deprecated.go, next.deprecated.go); +report("retired opencode ", current.deprecated.zen, next.deprecated.zen); -const decided = outcome({ - stale: shimStale( - { - familyApi: OPENCODE_FAMILY_API, - go: OPENCODE_GO_CATALOG, - planeApi: OPENCODE_PLANE_API, - zen: OPENCODE_ZEN_CATALOG, - }, - next - ), - write, -}); +const decided = outcome({ stale: shimStale(current, next), write }); if (decided.action === "write") { - let source = readFileSync(TARGET, "utf8"); - source = splice(source, "OPENCODE_GO_CATALOG", render(next.go)); - source = splice(source, "OPENCODE_ZEN_CATALOG", render(next.zen)); - source = spliceObject( - source, - "OPENCODE_PLANE_API", - renderPlaneApi(next.planeApi) - ); - source = spliceObject( - source, - "OPENCODE_FAMILY_API", - renderFamilyApi(next.familyApi) - ); - writeFileSync(TARGET, source); + writeFileSync(TARGET, rewriteShim(readFileSync(TARGET, "utf8"), next)); console.log(`\nwrote ${basename(TARGET.pathname)}`); } else { console.log( diff --git a/scripts/verify-catalog.ts b/scripts/verify-catalog.ts index 443389c..9a45166 100644 --- a/scripts/verify-catalog.ts +++ b/scripts/verify-catalog.ts @@ -40,12 +40,7 @@ * @module scripts/verify-catalog */ -import { - OPENCODE_FAMILY_API, - OPENCODE_GO_CATALOG, - OPENCODE_PLANE_API, - OPENCODE_ZEN_CATALOG, -} from "../src/catalog-data.ts"; +import * as catalogData from "../src/catalog-data.ts"; import { getLiveGoCatalog as liveGoCatalog, getLiveZenCatalog as liveZenCatalog, @@ -58,7 +53,7 @@ import { isCoreToolModel } from "../src/tool-fallback.ts"; import { planeModelFor } from "../src/utils/plane-model.ts"; import { planeProfileFor } from "../src/utils/plane-profile.ts"; import { isServableSdk, protocolForSdk } from "../src/utils/protocols.ts"; -import { shimData, shimStale } from "./catalog-shim.ts"; +import { shimData, shimStale, shippedShim } from "./catalog-shim.ts"; import { generatorArgs, readSource } from "./generator-kit.ts"; const PROBE = process.argv.includes("--probe"); @@ -108,16 +103,12 @@ if (OFFLINE) { ); } if (payload !== undefined) { - // The generator's own rule, over everything the shim exports: a - // difference in any catalog row, plane endpoint or family endpoint is - // staleness, and order is not. + // The generator's own rule, over everything the shim exports, read + // through the generator's own reader: a difference in any catalog row, + // plane endpoint, family endpoint or retired id is staleness, and order + // is not. const live = shimData(parseModelsDevCatalog(JSON.parse(payload))); - const shipped = { - familyApi: OPENCODE_FAMILY_API, - go: OPENCODE_GO_CATALOG, - planeApi: OPENCODE_PLANE_API, - zen: OPENCODE_ZEN_CATALOG, - }; + const shipped = shippedShim(catalogData); if (shimStale(shipped, live)) { fail( `shim is stale against ${from ?? MODELS_OPENCODE_URL} (run scripts/regenerate-catalog-shim.ts --write)` @@ -230,7 +221,7 @@ for (const [route, catalog, plane] of [ catalog, endpoint: "auto", entry: { models: declared }, - familyApi: OPENCODE_FAMILY_API[plane], + familyApi: catalogData.OPENCODE_FAMILY_API[plane], piModels: [], resolveRetryPolicy: () => ({}), route, @@ -271,8 +262,8 @@ console.log("\n4. routing"); const unroutable: string[] = []; let served = 0; for (const [route, catalog, family] of [ - ["opencode", getLiveZenCatalog(), OPENCODE_FAMILY_API.zen], - ["opencode-go", getLiveGoCatalog(), OPENCODE_FAMILY_API.go], + ["opencode", getLiveZenCatalog(), catalogData.OPENCODE_FAMILY_API.zen], + ["opencode-go", getLiveGoCatalog(), catalogData.OPENCODE_FAMILY_API.go], ] as const) { for (const spec of catalog) { const { model, error } = planeModelFor({ diff --git a/src/contracts/purge.ts b/src/contracts/purge.ts index a84791d..8029eed 100644 --- a/src/contracts/purge.ts +++ b/src/contracts/purge.ts @@ -37,15 +37,38 @@ export interface PurgeResult { /** Every id removed, in declaration order. Empty when nothing was retired. */ readonly removed: readonly PurgedModel[]; /** - * Whether the catalog had anything to say at all. + * Whether the list the removal judged by was read: the live catalog for + * `purge`, pi's installed catalog for `removeUnserved`. * - * `false` means the refresh did not land (offline, or a rejected reply) — the - * distinction matters because "nothing was deprecated" and "the catalog could - * not be read" otherwise produce the same empty list and the same sentence. + * `false` means that read did not land (offline, a rejected reply, a pi that + * cannot be loaded) — the distinction matters because "nothing was removed" + * and "the list could not be read" otherwise produce the same empty list and + * the same sentence. */ readonly catalogRead: boolean; } +/** + * What the card lists beside the purge row: the ids declared on the plugin's + * planes that pi's installed catalog cannot serve, and the catalog's last + * refresh error. + */ +export interface PurgeReview { + /** + * One row per declared id pi cannot serve, in entry then route order, an id + * two entries declare on one route once; empty when the profile declares no + * plane entry this plugin owns. + */ + readonly unserved: readonly PurgedModel[]; + /** + * Whether pi's installed catalog was read; `false` lists nothing, and the + * card says the catalog could not be read. + */ + readonly piRead: boolean; + /** Why the catalog's last refresh did not land, when it did not. */ + readonly catalogError?: string; +} + /** The remote namespace the host mounts and the card calls. */ export const PURGE_NAMESPACE = "opencodeModelPurge"; @@ -92,6 +115,48 @@ export const parsePurgeResult = (value: unknown): PurgeResult | undefined => { return { catalogRead, removed: rows }; }; +/** The longest catalog error the card renders. */ +const CATALOG_ERROR_MAX = 200; + +/** + * Parse a review, rejecting anything that is not one: rows through the same + * row check as a purge result, kept as `{ id, provider }`; `piRead` must be a + * boolean; `catalogError` is kept only when a string, cut to 200 characters. + * + * @param value - the decoded wire value. + * @returns the review, or `undefined` when it is not one. + */ +export const parsePurgeReview = (value: unknown): PurgeReview | undefined => { + if (typeof value !== "object" || value === null) { + return undefined; + } + const { catalogError, piRead, unserved } = value as { + catalogError?: unknown; + piRead?: unknown; + unserved?: unknown; + }; + if (!Array.isArray(unserved) || typeof piRead !== "boolean") { + return undefined; + } + const rows: PurgedModel[] = []; + for (const row of unserved) { + if (!isPurgedModel(row)) { + return undefined; + } + rows.push({ id: row.id, provider: row.provider }); + } + return { + piRead, + unserved: rows, + ...(typeof catalogError === "string" + ? { catalogError: catalogError.slice(0, CATALOG_ERROR_MAX) } + : {}), + }; +}; + +/** One result codec for the two methods that rewrite the profile. */ +const purgeResult = remoteValue("PurgeResult", parsePurgeResult); + /** * The purge namespace, as a contribution the client mounts. * @@ -103,7 +168,9 @@ export const parsePurgeResult = (value: unknown): PurgeResult | undefined => { * every contract under one package name (`REMOTE_CONTRACTS`). */ export const purgeRemote = defineRemote(PURGE_NAMESPACE, { - purge: { result: remoteValue("PurgeResult", parsePurgeResult) }, + purge: { result: purgeResult }, + review: { result: remoteValue("PurgeReview", parsePurgeReview) }, + removeUnserved: { result: purgeResult }, }); /** The one failure a purge reports: the profile cannot be rewritten here. */ @@ -125,6 +192,8 @@ declare module "@deepseek-ai/dsh-typert-protocol" { interface TypertRemoteNamespaceMap { opencodeModelPurge: { purge: () => Promise>; + review: () => Promise>; + removeUnserved: () => Promise>; }; } } diff --git a/src/cordis-context.ts b/src/cordis-context.ts index d9b7e8d..a080836 100644 --- a/src/cordis-context.ts +++ b/src/cordis-context.ts @@ -496,6 +496,25 @@ export const loadHostModules = async ( } }; +/** + * The libraries pi-ai runs on alone, or `undefined` while they cannot be read: + * the half of {@link loadHostModules} a caller that needs no pi-ai module uses + * (the purge's review reads pi's installed catalog), behind the same + * replaceable source. + * + * @param ctx - the plugin context. + */ +export const loadHostLibraries = async ( + ctx: unknown +): Promise => { + const source = replacementSource ?? defaultHostModuleSource; + try { + return await source.libraries(ctx); + } catch { + return undefined; + } +}; + /** One value of a launch-environment snapshot. */ export interface LaunchEnvironmentLike { readonly get: (name: string) => { readonly value?: string } | undefined; diff --git a/src/models-catalog.ts b/src/models-catalog.ts index 4b6e292..e0a2a6a 100644 --- a/src/models-catalog.ts +++ b/src/models-catalog.ts @@ -10,9 +10,18 @@ * responses to ensure that all models are present, fully described, and * available for DSH model discovery. * + * **One state, replaced whole.** Each plane holds its active rows and the ids + * the registry has retired, seeded from the shipped shim and REPLACED by a + * refresh that carries at least one active row for that plane, never merged + * into: an id the registry stops listing, or retires, leaves the live map on + * the refresh that says so. A failed or empty read replaces nothing (L12). + * The parser is pure, so a parse made anywhere else (a generator, an e2e + * file) cannot move the live retirements. + * * @module dsh-opencode-patch/models-catalog */ +import * as shim from "./catalog-data.ts"; import { OPENCODE_GO_CATALOG, OPENCODE_ZEN_CATALOG, @@ -111,22 +120,88 @@ const FALLBACK_MAX_OUTPUT_TOKENS = 131_072; */ export const MODELS_DEV_TIMEOUT_MS = 30_000; -let activeGoCatalog = new Map( - OPENCODE_GO_CATALOG.map((m) => [m.id, m]) -); -let activeZenCatalog = new Map( - OPENCODE_ZEN_CATALOG.map((m) => [m.id, m]) -); +/** Retired ids per plane, as the shim and the parser carry them. */ +export interface DeprecatedIds { + readonly go: string[]; + readonly zen: string[]; +} + +/** A list's string members, sorted; anything that is not a list is none. */ +const idList = (raw: unknown): string[] => + Array.isArray(raw) + ? raw.filter((id): id is string => typeof id === "string").toSorted() + : []; + +/** + * The retired ids a value carries: a record's `go` and `zen` string lists, + * strings only and sorted; anything else is an empty list per plane. + * + * Pure, and tolerant on purpose: it reads what the generated shim exports, + * which carries no retired ids until CI regenerates it with the generator that + * writes them. + * + * @param value - the shim's `OPENCODE_DEPRECATED_IDS`, or anything else. + * @returns the ids per plane. + */ +export const deprecatedIdsOf = (value: unknown): DeprecatedIds => + isRecord(value) + ? { go: idList(value.go), zen: idList(value.zen) } + : { go: [], zen: [] }; + +/** + * The ids the shipped shim records as retired, per plane. + * + * Read off the module namespace rather than through a named import: a named + * import of an export the generated file does not carry yet is a link error, + * and the file is regenerated by CI, never by hand. + */ +export const shippedDeprecatedIds = (): DeprecatedIds => { + const exported: Readonly> = shim; + return deprecatedIdsOf(exported.OPENCODE_DEPRECATED_IDS); +}; + /** - * Ids the most recent parse saw as `status: "deprecated"`, per plane. + * One plane's catalog: its active rows by id, and the ids the registry has + * retired. * - * Kept beside the active maps because the ADAPTER's own discovery needs it: - * `mergeDiscoveredModels` merges adapter rows before catalog rows, and pi's - * installed snapshot still carries ids the live catalog has retired. Dropping - * them from our catalog alone is not enough — the merge puts them back. + * The retired ids are kept beside the rows because the ADAPTER's own discovery + * needs them: `mergeDiscoveredModels` merges adapter rows before catalog rows, + * and pi's installed snapshot still carries ids the live catalog has retired. + * Dropping them from our catalog alone is not enough — the merge puts them + * back. Both always come from the same source: the shim, or one payload. + */ +interface PlaneState { + readonly rows: ReadonlyMap; + readonly deprecated: ReadonlySet; +} + +/** The state a fresh process starts from: the shim's rows and retirements. */ +const shimState = (): Record => { + const retired = shippedDeprecatedIds(); + return { + go: { + deprecated: new Set(retired.go), + rows: new Map(OPENCODE_GO_CATALOG.map((m) => [m.id, m])), + }, + zen: { + deprecated: new Set(retired.zen), + rows: new Map(OPENCODE_ZEN_CATALOG.map((m) => [m.id, m])), + }, + }; +}; + +/** The live catalog, per plane; replaced whole, never mutated. */ +let state: Record = shimState(); + +/** + * Why the most recent refresh attempt did not land on both planes, in one + * sentence; `undefined` once one has. Kept with the state it describes, so + * the card can say the catalog it shows is not the registry's latest. */ -const deprecatedGoIds = new Set(); -const deprecatedZenIds = new Set(); +let lastError: string | undefined; + +/** The longest {@link lastError} the card is handed. */ +const LAST_ERROR_MAX = 200; let lastRefreshedAt = 0; /** @@ -178,27 +253,22 @@ const catalogChanged = (): void => { } } }; +let refreshPromise: Promise | undefined; /** - * Whether the MOST RECENT refresh attempt read a usable payload. - * - * Distinct from {@link lastRefreshedAt}, which only advances on success and so - * answers "has this process ever refreshed?" — a question that stays `true` for - * hours after a failure. A caller that must know whether THIS attempt landed - * (the purge, which reports "nothing was deprecated" versus "the catalog could - * not be read") needs this one. + * The number of the newest refresh attempt. A forced refresh does not wait + * for one in flight, so two can overlap; only the newest writes an error into + * {@link lastError} and clears {@link refreshPromise} when it settles, so a + * slow older attempt cannot report its failure over a newer success. Any + * attempt that lands both planes clears {@link lastError}, because the state + * is then wholly that payload's, so a newer failure cannot outlive an older + * success that settled after it. */ -let lastRefreshSucceeded = false; -let refreshPromise: - | Promise<{ - go: readonly CatalogModelSpec[]; - zen: readonly CatalogModelSpec[]; - }> - | undefined; +let latestAttempt = 0; /** * Put the catalog back to the bundled shim, as a fresh process holds it. * - * The live maps, the retired-id sets and the refresh bookkeeping are module + * The live state, its last error and the refresh bookkeeping are module * state for the life of the process, which is right for the host and wrong for * a test: a case that refreshes from a fixture would otherwise decide what every * later case in the file sees. The sibling reset is `clearSessionUsageStore`; @@ -206,13 +276,11 @@ let refreshPromise: * needs none. */ export const resetCatalogState = (): void => { - activeGoCatalog = new Map(OPENCODE_GO_CATALOG.map((m) => [m.id, m])); - activeZenCatalog = new Map(OPENCODE_ZEN_CATALOG.map((m) => [m.id, m])); - deprecatedGoIds.clear(); - deprecatedZenIds.clear(); + state = shimState(); + lastError = undefined; lastRefreshedAt = 0; - lastRefreshSucceeded = false; refreshPromise = undefined; + latestAttempt += 1; generation += 1; }; @@ -236,6 +304,12 @@ export interface ParsedCatalogs { familyApi: { go: FamilyApi; zen: FamilyApi }; go: CatalogModelSpec[]; zen: CatalogModelSpec[]; + /** + * The ids each plane lists as `status: "deprecated"`, sorted. Answered, not + * recorded: the parse touches no module state, and the refresh is what + * installs them, with the rows of the same payload. + */ + deprecated: DeprecatedIds; } /** One plane's endpoint per SDK package (`""` = the provider's own default). */ @@ -333,10 +407,10 @@ const sanitizeReasoningOptions = ( const extractSpecs = ( modelsObj: Record, - defaultContext = 1_000_000, - deprecated?: Set -): CatalogModelSpec[] => { + defaultContext = 1_000_000 +): { specs: CatalogModelSpec[]; deprecated: string[] } => { const results: CatalogModelSpec[] = []; + const deprecated: string[] = []; for (const [id, rawModel] of Object.entries(modelsObj)) { if (!isRecord(rawModel)) { continue; @@ -356,12 +430,12 @@ const extractSpecs = ( // --probe` POSTs one token per id and fails on any offered model the // gateway no longer answers. if (rawModel.status === "deprecated") { - // Recorded, not merely dropped. A model the registry has retired must not + // Answered, not merely dropped. A model the registry has retired must not // come back through the ADAPTER's own discovery: `mergeDiscoveredModels` // merges adapter rows first, and pi's installed snapshot still lists ids - // the live catalog has retired. Without this set the merge re-adds every - // one, which is a picker led by models the vendor has retired. - deprecated?.add(id); + // the live catalog has retired. Without this list the merge re-adds + // every one, which is a picker led by models the vendor has retired. + deprecated.push(id); continue; } const name = @@ -435,7 +509,7 @@ const extractSpecs = ( ...(reasoning_options === undefined ? {} : { reasoning_options }), }); } - return results; + return { deprecated, specs: results }; }; /** @@ -462,8 +536,7 @@ export type CatalogPlane = Plane; export const findModelSpecOn = ( plane: CatalogPlane, modelId: string -): CatalogModelSpec | undefined => - plane === "go" ? activeGoCatalog.get(modelId) : activeZenCatalog.get(modelId); +): CatalogModelSpec | undefined => state[plane].rows.get(modelId); /** * Look up model specifications by model ID, preferring the Go plane. @@ -487,7 +560,7 @@ export const findModelSpecOn = ( * the two in that order. */ export const findModelSpec = (modelId: string): CatalogModelSpec | undefined => - activeGoCatalog.get(modelId) ?? activeZenCatalog.get(modelId); + state.go.rows.get(modelId) ?? state.zen.rows.get(modelId); /** * The spec a plane declares for a model, and the plane-blind one for a model @@ -523,13 +596,18 @@ export const specFor = ( /** * Safely parse raw models.dev JSON data for both opencode-go and opencode providers. * + * Pure: it reads its argument and touches no module state, so the generator, + * the e2e files and a refresh can all parse without moving the live catalog. + * * @param data - raw parsed JSON from `https://models.dev/api.json` - * @returns extracted model specifications for both Go and Zen + * @returns extracted model specifications for both Go and Zen, and the ids + * each plane lists as retired */ export const parseModelsDevCatalog = (data: unknown): ParsedCatalogs => { if (!isRecord(data)) { return { api: { go: "", zen: "" }, + deprecated: { go: [], zen: [] }, familyApi: { go: {}, zen: {} }, go: [], zen: [], @@ -544,24 +622,29 @@ export const parseModelsDevCatalog = (data: unknown): ParsedCatalogs => { ? data.opencode.models : {}; - deprecatedGoIds.clear(); - deprecatedZenIds.clear(); + const go = extractSpecs(goObj); + const zen = extractSpecs(zenObj); return { api: { go: providerApiFor(data["opencode-go"]), zen: providerApiFor(data.opencode), }, + deprecated: { + go: go.deprecated.toSorted(), + zen: zen.deprecated.toSorted(), + }, familyApi: { go: familyApiFor(data["opencode-go"]), zen: familyApiFor(data.opencode), }, - go: extractSpecs(goObj, 1_000_000, deprecatedGoIds), - zen: extractSpecs(zenObj, 1_000_000, deprecatedZenIds), + go: go.specs, + zen: zen.specs, }; }; /** - * Whether the most recent catalog parse saw `id` as retired on `plane`. + * Whether the live catalog holds `id` as retired on `plane`: the shim's own + * retirements, until a refresh lands that plane, and that payload's after. * * The complement of {@link findModelSpecOn}: a model can be absent from the * catalog because it is NEW or because it is RETIRED, and the two want opposite @@ -572,7 +655,7 @@ export const parseModelsDevCatalog = (data: unknown): ParsedCatalogs => { * @returns whether the registry has retired it. */ export const isDeprecatedModelOn = (plane: Plane, id: string): boolean => - (plane === "go" ? deprecatedGoIds : deprecatedZenIds).has(id); + state[plane].deprecated.has(id); /** * Whether a live parse has ever landed in this process. @@ -585,93 +668,164 @@ export const isDeprecatedModelOn = (plane: Plane, id: string): boolean => export const isCatalogFresh = (): boolean => lastRefreshedAt > 0; /** - * Whether the most recent refresh attempt actually read the registry. + * Why the most recent refresh did not land on both planes, in one sentence of + * at most 200 characters; `undefined` once one has, and in a fresh process. * - * Set to `false` when an attempt starts and only `true` by a payload that - * parsed, so a caller can distinguish "the catalog says none are deprecated" - * from "the catalog could not be read" — the two produce the same empty result - * and must not produce the same sentence. - * - * `refreshCatalog` never rejects, so its promise resolving says nothing about - * whether the read landed; this is the only way to tell. - * - * @returns whether the last attempt read a usable payload. + * @returns the last error, or `undefined`. */ -export const didCatalogRefreshSucceed = (): boolean => lastRefreshSucceeded; +export const catalogLastError = (): string | undefined => lastError; + +/** What one refresh attempt answers. */ +export interface CatalogRefresh { + /** + * Whether THIS attempt landed at least one plane. Distinct from + * {@link isCatalogFresh}, which stays true for hours after a failure: a + * caller that reports "nothing is retired" versus "the catalog could not be + * read" needs this one, and forces the refresh. A call inside the TTL reads + * nothing and answers `true`: the state it reports is a landed read's. + */ + readonly ok: boolean; + /** + * The retired ids per plane, read from the state after the attempt: the + * registry's when it landed, what the process already held when it did not. + */ + readonly deprecated: Readonly>; + /** The active rows per plane, read from the same state. */ + readonly go: readonly CatalogModelSpec[]; + readonly zen: readonly CatalogModelSpec[]; +} + +/** The route a plane's models are listed under, for the messages. */ +const ROUTE_OF_PLANE: Readonly> = { + go: "opencode-go", + zen: "opencode", +}; + +/** The state, as a refresh answers it. */ +const snapshot = (ok: boolean): CatalogRefresh => ({ + deprecated: { + go: [...state.go.deprecated].toSorted(), + zen: [...state.zen.deprecated].toSorted(), + }, + go: [...state.go.rows.values()], + ok, + zen: [...state.zen.rows.values()], +}); + +/** One sentence, capped, for {@link lastError}. */ +const capped = (message: string): string => + message.length > LAST_ERROR_MAX ? message.slice(0, LAST_ERROR_MAX) : message; + +/** What one read of the registry did. */ +type Attempt = + | { readonly landed: readonly Plane[] } + | { readonly error: string }; + +/** Read the registry once and install every plane it carries an active row for. */ +const attempt = async (fetchFn: typeof fetch): Promise => { + try { + const response = await fetchFn(MODELS_OPENCODE_URL, { + headers: { accept: "application/json" }, + signal: AbortSignal.timeout(MODELS_DEV_TIMEOUT_MS), + }); + if (!response.ok) { + return { + error: `models.opencode.ai answered ${String(response.status)}`, + }; + } + const parsed = parseModelsDevCatalog(await response.json()); + const landed: Plane[] = []; + const next = { ...state }; + for (const plane of ["go", "zen"] as const) { + // A plane is replaced only by a payload that carries at least one active + // row for it, and then its rows and its retired ids both come from that + // payload; a plane it carries none for keeps both (L12). + if (parsed[plane].length > 0) { + next[plane] = { + deprecated: new Set(parsed.deprecated[plane]), + rows: new Map(parsed[plane].map((m) => [m.id, m])), + }; + landed.push(plane); + } + } + state = next; + return { landed }; + } catch (error: unknown) { + return { error: error instanceof Error ? error.message : String(error) }; + } +}; /** - * Fetch and merge the latest live model specifications from the OpenCode - * catalog (`models.opencode.ai`). + * Fetch the latest live model specifications from the OpenCode catalog + * (`models.opencode.ai`) and REPLACE each plane the answer carries an active + * row for: its rows and its retired ids both come from that payload, and an + * id the registry no longer lists is gone. A plane the answer carries no + * active row for keeps what it had, and a failed read replaces nothing (L12). * - * Never throws: on network failure, timeout, or invalid reply, gracefully falls - * back to the current active catalog. Concurrent calls coalesce into one in-flight promise. + * Never throws: on network failure, timeout, or invalid reply, the current + * state is kept and the reason is kept beside it ({@link catalogLastError}). + * Concurrent calls coalesce into one in-flight promise; a forced call starts + * its own, and then only the newest attempt writes an error; any attempt that + * lands both planes clears it. * * @param fetchFn - fetch implementation to use (defaults to globalThis.fetch) * @param force - bypass TTL cache and force immediate refresh + * @returns whether this attempt landed, and the state after it. */ export const refreshCatalog = ( fetchFn: typeof fetch = globalThis.fetch, force = false -): Promise<{ - go: readonly CatalogModelSpec[]; - zen: readonly CatalogModelSpec[]; -}> => { +): Promise => { const now = Date.now(); if ( !force && lastRefreshedAt > 0 && now - lastRefreshedAt < CATALOG_REVALIDATION_TTL_MS ) { - return Promise.resolve({ - go: [...activeGoCatalog.values()], - zen: [...activeZenCatalog.values()], - }); + return Promise.resolve(snapshot(true)); } if (!force && refreshPromise !== undefined) { return refreshPromise; } + latestAttempt += 1; + const number = latestAttempt; + const newest = (): boolean => number === latestAttempt; refreshPromise = (async () => { - // Cleared BEFORE the attempt: a success that happens to precede a failed - // retry must not be reported as this attempt's outcome. - lastRefreshSucceeded = false; try { - const response = await fetchFn(MODELS_OPENCODE_URL, { - headers: { accept: "application/json" }, - signal: AbortSignal.timeout(MODELS_DEV_TIMEOUT_MS), - }); - if (response.ok) { - const json: unknown = await response.json(); - const parsed = parseModelsDevCatalog(json); - if (parsed.go.length > 0) { - const nextGo = new Map(activeGoCatalog); - for (const model of parsed.go) { - nextGo.set(model.id, model); - } - activeGoCatalog = nextGo; - } - if (parsed.zen.length > 0) { - const nextZen = new Map(activeZenCatalog); - for (const model of parsed.zen) { - nextZen.set(model.id, model); - } - activeZenCatalog = nextZen; - } - if (parsed.go.length > 0 || parsed.zen.length > 0) { - lastRefreshedAt = Date.now(); - lastRefreshSucceeded = true; - catalogChanged(); + const outcome = await attempt(fetchFn); + if ("error" in outcome) { + if (newest()) { + lastError = capped(outcome.error); } + return snapshot(false); } - } catch { - // Revalidation failure retains active catalogs and allows later retry + const missing = (["go", "zen"] as const).filter( + (plane) => !outcome.landed.includes(plane) + ); + if (missing.length === 0) { + // Any attempt that lands both planes leaves the state wholly its + // payload's, so no earlier failure describes it any more, whichever + // attempt that failure was. + lastError = undefined; + } else if (newest()) { + lastError = capped( + missing.length === 2 + ? "the registry's answer listed no active model" + : `the registry listed no active model for ${missing.map((plane) => ROUTE_OF_PLANE[plane]).join(", ")}` + ); + } + const ok = outcome.landed.length > 0; + if (ok) { + lastRefreshedAt = Date.now(); + catalogChanged(); + } + return snapshot(ok); } finally { - refreshPromise = undefined; + if (newest()) { + refreshPromise = undefined; + } } - return { - go: [...activeGoCatalog.values()], - zen: [...activeZenCatalog.values()], - }; })(); return refreshPromise; @@ -695,11 +849,11 @@ const triggerBackgroundRefresh = async ( * advanced by a refresh that returned something for at least one provider, so * an offline start keeps retrying on every read until the first success. * - * @param catalog - the active map to snapshot. + * @param plane - the plane whose rows to snapshot. * @param fetchFn - fetch implementation used for the background refresh. */ const readLiveCatalog = ( - catalog: ReadonlyMap, + plane: Plane, fetchFn: typeof fetch ): readonly CatalogModelSpec[] => { const now = Date.now(); @@ -709,7 +863,7 @@ const readLiveCatalog = ( ) { void triggerBackgroundRefresh(fetchFn); } - return [...catalog.values()]; + return [...state[plane].rows.values()]; }; /** @@ -719,7 +873,7 @@ const readLiveCatalog = ( */ export const getLiveGoCatalog = ( fetchFn: typeof fetch = globalThis.fetch -): readonly CatalogModelSpec[] => readLiveCatalog(activeGoCatalog, fetchFn); +): readonly CatalogModelSpec[] => readLiveCatalog("go", fetchFn); /** * Return the current Zen catalog immediately, triggering SWR revalidation if stale. @@ -728,7 +882,7 @@ export const getLiveGoCatalog = ( */ export const getLiveZenCatalog = ( fetchFn: typeof fetch = globalThis.fetch -): readonly CatalogModelSpec[] => readLiveCatalog(activeZenCatalog, fetchFn); +): readonly CatalogModelSpec[] => readLiveCatalog("zen", fetchFn); /** * The current catalog of one plane: {@link getLiveGoCatalog} or diff --git a/src/purge-service.ts b/src/purge-service.ts index f6b4309..c2f668f 100644 --- a/src/purge-service.ts +++ b/src/purge-service.ts @@ -1,6 +1,21 @@ /** * Host-side "purge deprecated models": rewrites the deployment's own provider - * declaration, deleting the model entries the live catalog has retired. + * declaration, deleting the model entries the catalog has retired. Its + * sibling, the ids pi cannot serve (`review`, `removeUnserved`), runs the + * same rewrite with another judge: the ids declared on the plugin's planes + * that pi's installed catalog does not describe, which pi-ai drops from the + * composer, and refuses the next Settings edit of, once the plugin is gone. + * + * **What "retired" is judged by.** The forced refresh's own answer + * (`CatalogRefresh.deprecated`): the registry's retired ids when the read + * lands, and what the process already holds when it does not — the shipped + * shim's own retirements, or an earlier refresh's. `catalogRead` says which. + * + * **One write per entry.** Every entry is judged before its write, and an + * entry with nothing to remove is not edited at all: on the real host a no-op + * edit still validates, rewrites the profile document and reconciles. An + * entry with something to remove gets exactly one edit, declarations and + * references together (`purgeEntryConfig`). * * **Why it edits the profile instead of filtering at read time.** A filter keeps * a second list of "what the user really means", and that list is invisible: the @@ -35,22 +50,21 @@ import { PURGE_UNAVAILABLE, purgeRemote, type PurgeResult, + type PurgeReview, type PurgedModel, } from "./contracts/purge.ts"; +import { loadHostLibraries } from "./cordis-context.ts"; import { markRemote } from "./host/remote.ts"; -import { - didCatalogRefreshSucceed, - isDeprecatedModelOn, - refreshCatalog, -} from "./models-catalog.ts"; +import { catalogLastError, refreshCatalog } from "./models-catalog.ts"; import { isRecord } from "./utils/guards.ts"; import { foreignCredentialsRealm, pluginMarkerOf, type RealmSide, } from "./utils/plane-ownership.ts"; +import { piUnservedIds } from "./utils/plane-profile.ts"; import { type Plane, PLANE_OF_ROUTE } from "./utils/planes.ts"; -import { PLANE_ROUTES } from "./utils/protocols.ts"; +import { PLANE_ROUTES, type PlaneRoute } from "./utils/protocols.ts"; /** A provider route the plugin knows how to read a plane from, in route order. */ const PLANES: readonly { route: string; plane: Plane }[] = PLANE_ROUTES.map( @@ -98,6 +112,9 @@ const idOf = (model: unknown): string | undefined => { return undefined; }; +/** Whether one `(route, id)` reference is to be removed. */ +type Judge = (route: string, id: string) => boolean; + /** * Whether `id` is retired on a route this plugin owns. * @@ -106,19 +123,29 @@ const idOf = (model: unknown): string | undefined => { * That includes a plane route only another plugin's entries declare (D27). * * @param foreign - the plane routes only another plugin's entries declare. + * @param retired - the ids retired on each plane, from one catalog answer. * @returns the judge for one `(route, id)` reference. */ const isRetiredOnOwnedRoute = - (foreign: ReadonlySet) => - (route: string, id: string): boolean => { + ( + foreign: ReadonlySet, + retired: ReadonlyMap> + ): Judge => + (route, id) => { const plane = PLANES.find((candidate) => candidate.route === route)?.plane; return ( plane !== undefined && !foreign.has(route) && - isDeprecatedModelOn(plane, id) + retired.get(plane)?.has(id) === true ); }; +/** Rows of `{ id, provider }` as a `(route, id)` judge. */ +const judgeOf = + (rows: readonly PurgedModel[]): Judge => + (route, id) => + rows.some((row) => row.provider === route && row.id === id); + /** A property read that a hostile or half-built value cannot throw out of. */ const readSafely = (value: unknown, key: string): unknown => { if (!isRecord(value)) { @@ -236,6 +263,135 @@ export const stripRetiredReferences = ( return { next, removed }; }; +/** + * One entry's config with every judged id removed: its declarations on the + * routes it owns, then every reference to one (`stripRetiredReferences`). + * + * PURE, so the purge can judge an entry before writing it and write it with + * one edit: the pre-check and the edit's own callback run the same function. + * + * @param config - the entry's config, verbatim. + * @param ownedRoutes - the plane routes this entry declares that the plugin + * may rewrite; a route not listed is never filtered. + * @param isRetired - whether `id` is to be removed from `route`'s declaration + * in THIS entry. + * @param isReferenced - whether a reference to `(route, id)` is to be + * removed; the declaration judge when omitted. The removal of the ids pi + * cannot serve passes a route-wide judge here, because a reference names a + * route and not the entry that declares it. + * @returns the config to write (`config` itself when nothing matched), and + * what went, declarations first. + */ +export const purgeEntryConfig = ( + config: Record, + ownedRoutes: readonly string[], + isRetired: Judge, + isReferenced: Judge = isRetired +): { next: Record; removed: PurgedModel[] } => { + const removed: PurgedModel[] = []; + let next = config; + const providers = isRecord(config.providers) ? config.providers : undefined; + if (providers !== undefined) { + const rewritten: Record = { ...providers }; + for (const { route } of PLANES) { + const declared = ownedRoutes.includes(route) + ? modelsOf(providers[route]) + : undefined; + if (declared === undefined) { + continue; + } + const kept = declared.filter((model) => { + const id = idOf(model); + if (id === undefined || !isRetired(route, id)) { + return true; + } + removed.push({ id, provider: route }); + return false; + }); + if (kept.length !== declared.length) { + rewritten[route] = { ...(providers[route] as object), models: kept }; + } + } + if (removed.length > 0) { + next = { ...config, providers: rewritten }; + } + } + const references = stripRetiredReferences(next, isReferenced); + return { + next: references.next, + removed: [...removed, ...references.removed], + }; +}; + +/** The config an editor entry carries, when its options hold one. */ +const configOf = (entry: unknown): Record | undefined => { + const options = readSafely(entry, "options"); + const config = isRecord(options) ? options.config : undefined; + return isRecord(config) ? config : undefined; +}; + +/** Which entries' plane routes the plugin may rewrite, and a judge's guard. */ +interface Ownership { + /** Each entry that declares an owned plane route, with those routes. */ + readonly ownedRoutes: ReadonlyMap; + /** The plane routes only another plugin's entries declare (D27). */ + readonly foreignOnly: ReadonlySet; +} + +/** What `rewrite` removes: declarations judged per entry, references per route. */ +interface Judges { + /** The judge for one entry's own declarations. */ + readonly declarations: (entry: unknown) => Judge; + /** The judge for a reference, which names a route and not an entry. */ + readonly references: Judge; +} + +/** + * Rewrite every entry the judges find something in: one loop over the + * editor's entries, a pure pre-check, and exactly one edit for an entry that + * changes. + * + * @param editor - the config editor. + * @param ownership - which entries' plane routes the plugin may rewrite. + * @param judges - whether one `(route, id)` declaration or reference is to go. + * @returns every reference removed, in entry order. + */ +const rewrite = async ( + editor: ConfigEditorFace, + ownership: Ownership, + judges: Judges +): Promise => { + const removed: PurgedModel[] = []; + for (const entry of editor.entries()) { + const config = configOf(entry); + if (config === undefined) { + continue; + } + const routes = ownership.ownedRoutes.get(entry) ?? []; + const judge = judges.declarations(entry); + const purgeOf = (current: Record) => + purgeEntryConfig(current, routes, judge, judges.references); + // Decided before the write, so an entry with nothing to remove is not + // rewritten at all: on the real host a no-op edit still validates, + // rewrites the profile document and reconciles. + if (purgeOf(config).removed.length === 0) { + continue; + } + // Recomputed on the config the editor hands the change, which is the one + // it writes, and appended only once the edit resolved: an edit that + // throws propagates before the append, so a rejected edit reports nothing. + let entryRemoved: PurgedModel[] = []; + // oxlint-disable-next-line no-await-in-loop -- one write at a time, in entry order: each edit locks and rewrites the same profile document. + await editor.edit(entry, (current) => { + const { next, removed: gone } = purgeOf(current); + entryRemoved = gone; + return next; + }); + removed.push(...entryRemoved); + } + return removed; +}; + export class ModelPurgeService extends TypertRemoteService { constructor(ctx: unknown) { if (!isRecord(ctx)) { @@ -245,16 +401,8 @@ export class ModelPurgeService extends TypertRemoteService { super(ctx as never, PURGE_NAMESPACE); } - /** - * Delete every declared model the live catalog marks `deprecated`. - * - * One network read first, forced: the shipped shim cannot answer this - * question, because a retired model is dropped from the active catalog rather - * than kept with a flag. `catalogRead` reports whether that read landed, so the - * card can say "the catalog reports none" instead of implying it when the - * refresh failed. - */ - async purge(): Promise { + /** The config editor, or the refusal every method answers without one. */ + private editor(): ConfigEditorFace { const editor = asEditor(this.ctx.get?.("configEditor")); if (editor === undefined) { throw new RemoteError( @@ -263,15 +411,14 @@ export class ModelPurgeService extends TypertRemoteService { { configured: false, retainPrevious: false, retryable: false } ); } + return editor; + } - await refreshCatalog(undefined, true); - // **Whether THIS attempt read the registry**, not whether one ever did. - // `refreshCatalog` never rejects, and `isCatalogFresh()` answers "has this - // process refreshed at all?" — true for hours after a failure. Reporting - // that as `catalogRead` told the card "nothing is deprecated" for a read - // that never happened. - const catalogRead = didCatalogRefreshSucceed(); - + /** + * Which entries' plane routes the plugin may rewrite, or the refusal when it + * may rewrite none. + */ + private ownership(editor: ConfigEditorFace): Ownership { // The service's own context decides the realm: it resolves `credentials` // in the process-wide realm, where the user's own rows do. const own: RealmSide = { context: this.ctx }; @@ -300,82 +447,143 @@ export class ModelPurgeService extends TypertRemoteService { { configured: false, retainPrevious: false, retryable: false } ); } - const isRetired = isRetiredOnOwnedRoute( - new Set([...declaredForeign].filter((route) => !declaredOwned.has(route))) - ); + return { + foreignOnly: new Set( + [...declaredForeign].filter((route) => !declaredOwned.has(route)) + ), + ownedRoutes, + }; + } - const removed: PurgedModel[] = []; - for (const [entry, routes] of ownedRoutes) { - // Collected per entry, then appended. NOT a fix for anything: an `edit` - // that throws propagates out of `purge()` before the return, so the report - // can never describe a rejected edit either way (checked, so this comment - // does not claim a failure mode that cannot occur). It is simply the - // narrower scope — each entry's removals stay attributable to that entry, - // which is what a partial-failure path would need if one is ever added. - const entryRemoved: PurgedModel[] = []; - await editor.edit(entry, (current) => { - const providers = isRecord(current.providers) - ? { ...current.providers } - : {}; - for (const { route, plane } of PLANES) { - if (!routes.includes(route)) { - continue; - } - const declared = modelsOf(providers[route]); - if (declared === undefined) { - continue; - } - const kept = declared.filter((model) => { - const id = idOf(model); - if (id === undefined || !isDeprecatedModelOn(plane, id)) { - return true; - } - entryRemoved.push({ provider: route, id }); - return false; - }); - if (kept.length !== declared.length) { - providers[route] = { - ...(providers[route] as object), - models: kept, - }; - } + /** + * The ids each owned plane route declares that pi's installed catalog cannot + * serve, per entry: each entry is judged by its own block (its own `api` + * among it), so an id one entry cannot serve is never judged unserved in + * another. `undefined` when pi cannot be read. + */ + private async unserved( + ownership: Ownership + ): Promise | undefined> { + const libraries = await loadHostLibraries(this.ctx); + if (libraries === undefined) { + return undefined; + } + const byEntry = new Map(); + for (const [entry, routes] of ownership.ownedRoutes) { + const providers = providersOf(entry); + const rows: PurgedModel[] = []; + for (const route of routes) { + for (const id of piUnservedIds( + providers?.[route], + // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- `routes` holds only `PLANE_ROUTES` members (`planeRoutesOf` filters by them); the cast names that. + libraries.builtinModels(route as PlaneRoute) + )) { + rows.push({ id, provider: route }); } - return { ...current, providers }; - }); - removed.push(...entryRemoved); + } + byEntry.set(entry, rows); } + return byEntry; + } - // **Every other surface that names a model by id.** The provider lists above - // are what the picker reads; these are what actually CALL a model, and they - // live in entries that declare no provider at all — which is why the sweep - // above could not see them. A retired id here is worse than a stale picker - // row: compaction that cannot resolve its summariser fails the checkpoint, - // and the session then ends every turn on `max-tokens`. - for (const entry of editor.entries()) { - const options = isRecord(entry) ? entry.options : undefined; - const config = isRecord(options) ? options.config : undefined; - if (!isRecord(config)) { - continue; + /** + * Delete every declared model, and every reference to one, that the catalog + * marks `deprecated`. + * + * One network read first, forced, and the removal is judged by that read's + * own answer: the registry's retired ids when it lands, and what the + * process already holds when it does not (the shipped shim's retirements, + * or an earlier refresh's). `catalogRead` reports whether the read landed, + * so the card can say "the catalog reports none" only when it did. + */ + async purge(): Promise { + const editor = this.editor(); + const refresh = await refreshCatalog(undefined, true); + const ownership = this.ownership(editor); + const retired = new Map>( + PLANES.map(({ plane }) => [plane, new Set(refresh.deprecated[plane])]) + ); + const judge = isRetiredOnOwnedRoute(ownership.foreignOnly, retired); + const removed = await rewrite(editor, ownership, { + declarations: () => judge, + references: judge, + }); + return { catalogRead: refresh.ok, removed }; + } + + /** + * The ids declared on the plugin's own plane entries that pi's installed + * catalog cannot serve, and the catalog's last refresh error. + * + * pi-ai refuses such an id once the plugin is gone ("needs an api"), so this + * is what the card lists before the plugin is removed. No network, no edit. + * + * An id two entries declare on one route is listed once. A profile with no + * plane entry this plugin owns lists nothing and still answers the + * catalog's last error, which does not depend on what the profile declares; + * only a composition with no config editor refuses. + */ + async review(): Promise { + const catalogError = catalogLastError(); + const ownership = this.ownershipOrNone(this.editor()); + const byEntry = await this.unserved(ownership); + const seen = new Set(); + const unserved: PurgedModel[] = []; + for (const rows of byEntry?.values() ?? []) { + for (const row of rows) { + const key = `${row.provider}\u0000${row.id}`; + if (!seen.has(key)) { + seen.add(key); + unserved.push(row); + } } - // Decided before the write so an entry with nothing to strip is not - // rewritten at all: an unconditional edit would mark every entry dirty on - // every click. - if (stripRetiredReferences(config, isRetired).removed.length === 0) { - continue; + } + return { + piRead: byEntry !== undefined, + unserved, + ...(catalogError === undefined ? {} : { catalogError }), + }; + } + + /** {@link ownership}, or no owned entry where it refuses for want of one. */ + private ownershipOrNone(editor: ConfigEditorFace): Ownership { + try { + return this.ownership(editor); + } catch (error: unknown) { + if (error instanceof RemoteError && error.code === PURGE_UNAVAILABLE) { + return { foreignOnly: new Set(), ownedRoutes: new Map() }; } - const entryRemoved: PurgedModel[] = []; - await editor.edit(entry, (current) => { - const { next, removed: gone } = stripRetiredReferences( - current, - isRetired - ); - entryRemoved.push(...gone); - return next; - }); - removed.push(...entryRemoved); + throw error; } + } - return { removed, catalogRead }; + /** + * Remove the ids {@link review} lists, and every reference to one, with one + * edit per entry that changes. Nothing is removed when pi's installed + * catalog cannot be read, and `catalogRead` then says so. No catalog read. + */ + async removeUnserved(): Promise { + const editor = this.editor(); + const ownership = this.ownership(editor); + const byEntry = await this.unserved(ownership); + if (byEntry === undefined) { + return { catalogRead: false, removed: [] }; + } + // A declaration is judged by its own entry's rows: an entry that sets a + // route-level `api` lists none, so it keeps an id another entry on the + // same route cannot serve. A reference names a route only, so it is + // judged by every owned entry's rows; those hold owned routes only, so a + // reference to a route only another plugin's entries declare is never + // judged (D27). Route-wide on purpose: two owned entries declaring one + // route is a composition the host's registry refuses (the second + // registration of a provider is a DUPLICATE_ADAPTER), so which entry + // serves the route once the plugin is gone depends on apply order, and a + // reference cannot be attributed to the one that keeps the id. + const removed = await rewrite(editor, ownership, { + declarations: (entry) => judgeOf(byEntry.get(entry) ?? []), + references: judgeOf([...byEntry.values()].flat()), + }); + return { catalogRead: true, removed }; } } diff --git a/src/settings-card.tsx b/src/settings-card.tsx index 83b674c..466127a 100644 --- a/src/settings-card.tsx +++ b/src/settings-card.tsx @@ -16,12 +16,13 @@ import { } from "@deepseek-ai/dsh-client-ui-primitives"; import React from "react"; +import type { PurgeReview } from "./contracts/purge.ts"; import type { GoUsage } from "./contracts/usage.ts"; import { SettingsBooleanField } from "./settings-boolean-field.tsx"; import { SettingsChoiceField } from "./settings-choice-field.tsx"; import { withBundleCopy, type Translate } from "./settings-copy.ts"; import { CARD_FIELDS, type CardFieldSpec } from "./settings-fields.ts"; -import type { PurgeOutcome } from "./settings-purge.ts"; +import type { PurgeOutcome, ReviewOutcome } from "./settings-purge.ts"; import { StoreInspectRow } from "./settings-store-inspect.tsx"; import type { StoreInspectOutcome } from "./settings-store.ts"; import { UsageSummary } from "./settings-usage.tsx"; @@ -95,8 +96,78 @@ export const purgeLine = ( }; }; +/** + * What a review says: the catalog's last error, the ids pi cannot serve + * grouped by provider in first-seen order (`opencode: a, b · opencode-go: c`), + * and that pi's installed catalog could not be read, when it could not (a + * review that read nothing lists nothing, and would otherwise say nothing). + * Each line is absent when there is nothing to say. + */ +export const reviewLines = ( + t: Translate, + review: PurgeReview +): { error?: string; piUnread?: string; unserved?: string } => { + const byProvider = new Map(); + for (const { id, provider } of review.unserved) { + byProvider.set(provider, [...(byProvider.get(provider) ?? []), id]); + } + return { + ...(review.catalogError === undefined + ? {} + : { error: `${t("catalogLastError")}: ${review.catalogError}` }), + ...(review.piRead ? {} : { piUnread: t("unservedPiUnreadReview") }), + ...(byProvider.size === 0 + ? {} + : { + unserved: [...byProvider] + .map(([provider, ids]) => `${provider}: ${ids.join(", ")}`) + .join(" · "), + }), + }; +}; + +/** + * What one removal of the unserved ids says, and whether it reads as a + * warning: a refusal as the purge's, and "nothing removed" told apart from + * "pi's catalog could not be read". + */ +export const unservedLine = ( + t: Translate, + outcome: PurgeOutcome +): { line: string; warn: boolean } => { + if (outcome.kind !== "purged") { + return purgeLine(t, outcome); + } + if (outcome.result.removed.length === 0) { + return outcome.result.catalogRead + ? { line: t("unservedNothing"), warn: false } + : { line: t("unservedPiUnread"), warn: true }; + } + return { + line: `${String(outcome.result.removed.length)} ${t("unservedRemoved")}`, + warn: false, + }; +}; + +/** One outcome line under an action, in the warn colour when it warns. */ +const OutcomeLine: React.FC<{ line: string; warn: boolean }> = (props) => ( +
+ {props.line} +
+); + const PurgeRow: React.FC<{ onPurge: () => Promise; + onReview?: () => Promise; + onRemoveUnserved?: () => Promise; t: Translate; }> = (props) => { const [state, setState] = React.useState<{ @@ -104,13 +175,55 @@ const PurgeRow: React.FC<{ line?: string; warn?: boolean; }>({ busy: false }); + const [removal, setRemoval] = React.useState<{ + busy: boolean; + line?: string; + warn?: boolean; + }>({ busy: false }); + const [review, setReview] = React.useState(); + // Bumped after each purge or removal settles, so the review is read again. + const [round, setRound] = React.useState(0); + + // The latest callback, read through a ref: the page builds a fresh closure + // on every render, and a review per parent render is not what this asks. + const reviewRef = React.useRef(props.onReview); + reviewRef.current = props.onReview; + const reviews = props.onReview !== undefined; + React.useEffect(() => { + const onReview = reviewRef.current; + let live = true; + if (reviews && onReview !== undefined) { + void (async () => { + const outcome = await onReview(); + if (live) { + setReview(outcome.kind === "review" ? outcome.review : undefined); + } + })(); + } + return () => { + live = false; + }; + }, [reviews, round]); const run = async (): Promise => { setState({ busy: true }); const outcome = await props.onPurge(); setState({ busy: false, ...purgeLine(props.t, outcome) }); + setRound((value) => value + 1); + }; + + const remove = async ( + onRemoveUnserved: () => Promise + ): Promise => { + setRemoval({ busy: true }); + const outcome = await onRemoveUnserved(); + setRemoval({ busy: false, ...unservedLine(props.t, outcome) }); + setRound((value) => value + 1); }; + const lines = review === undefined ? {} : reviewLines(props.t, review); + const { onRemoveUnserved } = props; + return (
{state.line !== undefined && ( -
- {state.line} + + )} + {lines.error !== undefined && } + {/* + The ids pi cannot serve: listed only when there is something to act on, + because the removal deletes models the plugin serves today. It is the + step before removing the plugin, which the hint says. + */} + {lines.unserved !== undefined && onRemoveUnserved !== undefined && ( +
+
+
+
+ {props.t("unservedTitle")} +
+
+ {props.t("unservedHint")} +
+
{lines.unserved}
+
+ +
)} + {lines.piUnread !== undefined && onRemoveUnserved !== undefined && ( + + )} + {removal.line !== undefined && ( + + )}
); }; @@ -181,6 +336,14 @@ export interface CardProps { * row, because it invites a click that explains nothing. */ purgeDeprecated?: () => Promise; + /** + * The Host's review of the declared ids pi cannot serve, read beside the + * purge row on mount and after each action settles; absent, the row is as + * it was. + */ + reviewPurge?: () => Promise; + /** The Host's removal of those ids; the block renders only with it. */ + removeUnserved?: () => Promise; /** * The Host's local-store inspection, absent when no store service is mounted. * Rendered only when present, for the same reason the purge row is: a button @@ -319,7 +482,12 @@ export const OpencodeCard: React.FC = (props: CardProps) => { )} {props.purgeDeprecated !== undefined && ( - + )} {/* A Settings write takes the loader's volatile-only path and the plugin diff --git a/src/settings-copy.ts b/src/settings-copy.ts index 2461efc..2b56241 100644 --- a/src/settings-copy.ts +++ b/src/settings-copy.ts @@ -134,6 +134,19 @@ export const en = { "Nothing removed, but the catalog could not be read — try again when online.", purgeUnavailable: "Unavailable: this composition has no config editor.", purgeFailed: "Purge failed", + catalogLastError: "The last catalog refresh failed", + unservedTitle: "Models llm-pi-ai cannot serve", + unservedHint: + "These ids are declared on opencode or opencode-go and are missing from pi's installed catalog. This plugin serves them; without it, llm-pi-ai drops them from the composer and refuses the next Settings edit of that provider until they are removed. Remove them before removing the plugin.", + unservedAction: "Remove", + unservedBusy: "Removing…", + unservedRemoved: "model reference(s) removed from your configuration", + unservedNothing: + "Nothing to remove — pi's installed catalog serves every declared id.", + unservedPiUnread: + "Nothing was removed: pi's installed catalog could not be read.", + unservedPiUnreadReview: + "pi's installed catalog could not be read, so the ids it cannot serve are not listed.", usageSummaryTitle: "Go usage", usageSummaryStatusOk: "Healthy", usageSummaryStatusLimited: "Limit reached", @@ -266,6 +279,17 @@ export const zh: Record = { purgeCatalogUnread: "没有移除任何条目,但目录读取失败——联网后重试。", purgeUnavailable: "不可用:此组合没有 config editor。", purgeFailed: "清理失败", + catalogLastError: "上次目录刷新失败", + unservedTitle: "llm-pi-ai 无法提供的模型", + unservedHint: + "这些 id 声明在 opencode 或 opencode-go 上,但 pi 已安装的目录里没有。本插件可以提供它们;没有本插件时,llm-pi-ai 会把它们从输入区移除,并拒绝该 provider 的下一次设置编辑,直到它们被移除。请在移除插件之前先移除它们。", + unservedAction: "移除", + unservedBusy: "移除中…", + unservedRemoved: "处模型引用已从配置中移除", + unservedNothing: "没有需要移除的内容——pi 已安装的目录能提供每个声明的 id。", + unservedPiUnread: "没有移除任何条目:读不到 pi 已安装的目录。", + unservedPiUnreadReview: + "读不到 pi 已安装的目录,所以无法列出它不能提供的 id。", usageSummaryTitle: "Go 用量", usageSummaryStatusOk: "状态正常", usageSummaryStatusLimited: "已达限额", diff --git a/src/settings-page.tsx b/src/settings-page.tsx index 3fb3544..4c02905 100644 --- a/src/settings-page.tsx +++ b/src/settings-page.tsx @@ -20,7 +20,11 @@ import { USAGE_NAMESPACE, usageRemote } from "./contracts/usage.ts"; import { OpencodeCard } from "./settings-card.tsx"; import { en, withBundleCopy, zh, type CopyKey } from "./settings-copy.ts"; import { SPECS } from "./settings-fields.ts"; -import { purgeDeprecatedModels } from "./settings-purge.ts"; +import { + purgeDeprecatedModels, + removeUnservedModels, + reviewPurge, +} from "./settings-purge.ts"; import { callUsageRead, findRemoteCall, @@ -662,6 +666,10 @@ export const apply = (ctx: ClientContext): void => { // The profile rewrite: needs the host's config editor, so it is a // Remote, and the card shows its outcome rather than assuming one. purgeDeprecated: () => purgeDeprecatedModels(ctx), + // Beside it, the declared ids pi cannot serve without this + // plugin, and their removal: the step before removing it. + reviewPurge: () => reviewPurge(ctx), + removeUnserved: () => removeUnservedModels(ctx), // What the readOpencodeStore switch would actually read: the // host inspects its own OpenCode store and answers a sanitized // summary, so the card can show the account without the secret. diff --git a/src/settings-purge.ts b/src/settings-purge.ts index c7dcd58..4022c3e 100644 --- a/src/settings-purge.ts +++ b/src/settings-purge.ts @@ -1,8 +1,9 @@ /** - * The card's one destructive action: ask the host to delete the retired models - * this deployment declares. + * The card's destructive actions: ask the host to delete the retired models + * this deployment declares, and the ids pi cannot serve; and the review that + * lists those ids beside the purge row. * - * The call is a Remote, like the quota read: the purge needs the profile and the + * The calls are Remotes, like the quota read: they need the profile and the * config editor, neither of which a browser has. Every failure is named rather * than collapsed into `undefined`, because "no service", "no config editor" and * "the host refused" are three different problems for whoever clicks it. @@ -10,7 +11,11 @@ * @module dsh-opencode-patch/settings-purge */ -import { purgeRemote, type PurgeResult } from "./contracts/purge.ts"; +import { + purgeRemote, + type PurgeResult, + type PurgeReview, +} from "./contracts/purge.ts"; import { callRemote, type RemoteOutcome } from "./settings-remote.ts"; /** What one click produced, in a shape the card can render without guessing. */ @@ -19,22 +24,34 @@ export type PurgeOutcome = | { readonly kind: "unavailable" } | { readonly kind: "failed"; readonly message: string }; +/** What the review answered, in the same three shapes. */ +export type ReviewOutcome = + | { readonly kind: "review"; readonly review: PurgeReview } + | { readonly kind: "unavailable" } + | { readonly kind: "failed"; readonly message: string }; + +/** One call's outcome, before it is named for its caller. */ +type Settled = + | { readonly kind: "value"; readonly value: Value } + | { readonly kind: "unavailable" } + | { readonly kind: "failed"; readonly message: string }; + /** - * Ask the host to purge, once. - * - * Through the one unwrap (`callRemote`): the host's own failure comes first, - * in its own words, and the result is PARSED by the contract's whitelist, - * never cast. + * Call one purge method through the one unwrap (`callRemote`) and name the + * outcome: the host's own failure first, in its own words, and the result + * PARSED by the contract's whitelist, never cast. * - * @param scope - the settings scope the card was rendered with. + * @param call - the call, as `callRemote` answers it. + * @param invalid - the sentence for an answer the contract rejects. * @returns the outcome; never throws. */ -export const purgeDeprecatedModels = async ( - scope: unknown -): Promise => { - let outcome: RemoteOutcome; +const settle = async ( + call: () => Promise>, + invalid: string +): Promise> => { + let outcome: RemoteOutcome; try { - outcome = await callRemote(scope, purgeRemote, "purge"); + outcome = await call(); } catch (error: unknown) { return { kind: "failed", @@ -42,9 +59,6 @@ export const purgeDeprecatedModels = async ( }; } if (outcome.kind === "unavailable") { - console.warn( - "[dsh-opencode-patch] purge: no opencodeModelPurge service on the remote" - ); return { kind: "unavailable" }; } if (outcome.kind === "refused") { @@ -54,10 +68,74 @@ export const purgeDeprecatedModels = async ( }; } if (outcome.kind === "invalid") { - return { - kind: "failed", - message: "the host answered something that is not a purge result", - }; + return { kind: "failed", message: invalid }; + } + return { kind: "value", value: outcome.value }; +}; + +/** A settled purge result, named for the card. */ +const asPurge = (settled: Settled): PurgeOutcome => + settled.kind === "value" + ? { kind: "purged", result: settled.value } + : settled; + +/** + * Ask the host to purge, once. + * + * @param scope - the settings scope the card was rendered with. + * @returns the outcome; never throws. + */ +export const purgeDeprecatedModels = async ( + scope: unknown +): Promise => { + const settled = await settle( + () => callRemote<"purge", PurgeResult>(scope, purgeRemote, "purge"), + "the host answered something that is not a purge result" + ); + if (settled.kind === "unavailable") { + console.warn( + "[dsh-opencode-patch] purge: no opencodeModelPurge service on the remote" + ); } - return { kind: "purged", result: outcome.value }; + return asPurge(settled); +}; + +/** + * Ask the host which declared ids pi cannot serve. Says nothing in the console + * when the service is absent: the purge row's own call already says it once. + * + * @param scope - the settings scope the card was rendered with. + * @returns the outcome; never throws. + */ +export const reviewPurge = async (scope: unknown): Promise => { + const settled = await settle( + // Named: the contract's methods answer different results, so the + // result type is the method's, not one inferred across them. + () => callRemote<"review", PurgeReview>(scope, purgeRemote, "review"), + "the host answered something that is not a purge review" + ); + return settled.kind === "value" + ? { kind: "review", review: settled.value } + : settled; }; + +/** + * Ask the host to remove the ids pi cannot serve, once. + * + * @param scope - the settings scope the card was rendered with. + * @returns the outcome; never throws. + */ +export const removeUnservedModels = async ( + scope: unknown +): Promise => + asPurge( + await settle( + () => + callRemote<"removeUnserved", PurgeResult>( + scope, + purgeRemote, + "removeUnserved" + ), + "the host answered something that is not a purge result" + ) + ); diff --git a/src/utils/plane-profile.ts b/src/utils/plane-profile.ts index abfd2aa..3954d3d 100644 --- a/src/utils/plane-profile.ts +++ b/src/utils/plane-profile.ts @@ -651,3 +651,39 @@ const resolveModels = ( } return models; }; + +/** + * The ids a plane entry declares that pi-ai cannot serve without the plugin: + * the mirror of its "needs an api" check (`llm-pi-ai` `resolveEntry`: the + * route's `api`, else the installed entry's, else the one api the installed + * catalog shares), the one refusal the plugin lifts (D15) and pi-ai brings + * back once the plugin is gone. + * + * @param entry - the raw provider entry. + * @param piModels - pi's installed catalog for the route. + * @returns each declared id pi's list lacks, once, in declaration order; none + * when the entry names an api or pi's models all share one. + */ +export const piUnservedIds = ( + entry: unknown, + piModels: readonly PlanePiModel[] +): string[] => { + if (!isRecord(entry) || !Array.isArray(entry.models)) { + return []; + } + if (typeof entry.api === "string" && entry.api.length > 0) { + return []; + } + if (new Set(piModels.map((model) => model.api)).size === 1) { + return []; + } + const known = new Set(piModels.map((model) => model.id)); + const unserved = new Set(); + for (const model of entry.models) { + const id: unknown = isRecord(model) ? model.id : model; + if (typeof id === "string" && !known.has(id)) { + unserved.add(id); + } + } + return [...unserved]; +}; diff --git a/test/catalog-refresh.test.ts b/test/catalog-refresh.test.ts index 36809a0..b26c729 100644 --- a/test/catalog-refresh.test.ts +++ b/test/catalog-refresh.test.ts @@ -5,22 +5,43 @@ */ import { describe, expect, it, vi } from "vitest"; +import { payload, registryOf, shippedShimData } from "./support/catalogs.ts"; import { OPENCODE_GO_CATALOG, OPENCODE_ZEN_CATALOG, + catalogGeneration, + catalogLastError, + deprecatedIdsOf, + findModelSpecOn, getLiveGoCatalog, getLiveZenCatalog, + isDeprecatedModelOn, parseModelsDevCatalog, refreshCatalog, resetCatalogState, + shippedDeprecatedIds, } from "./support/src.ts"; +/** A fetch answering one catalog payload, or a failure status. */ +const answering = (body: unknown, status = 200): typeof fetch => + (async () => + status === 200 + ? Response.json(body) + : new Response("no", { status })) as unknown as typeof fetch; + +/** The ids one plane's live catalog holds, in its order. */ +const liveIds = (plane: "go" | "zen"): string[] => + (plane === "go" ? getLiveGoCatalog : getLiveZenCatalog)( + answering({}, 503) + ).map((model) => model.id); + describe("catalog · the live registry read", () => { it("parseModelsDevCatalog handles malformed data gracefully", () => { // `api` and `familyApi` are carried alongside the arrays and are empty when // nothing declares them — not `undefined`, so callers never guard two shapes. const empty = { api: { go: "", zen: "" }, + deprecated: { go: [], zen: [] }, familyApi: { go: {}, zen: {} }, go: [], zen: [], @@ -90,61 +111,350 @@ describe("catalog · the live registry read", () => { expect(parsed.zen[0]?.name).toBe("Zen Free Test"); }); - it("getLiveGoCatalog and getLiveZenCatalog return local shims and revalidate", async () => { - const initialGo = getLiveGoCatalog(); - expect(initialGo.length).toBe(OPENCODE_GO_CATALOG.length); - const initialZen = getLiveZenCatalog(); - // Equal to the generated data: the shim was regenerated, so the retired ids - // (`claude-sonnet-4`, and the three dead rows) are no longer IN it. Retirement - // still filters at load; it just has nothing left to remove from this set. - expect(initialZen.length).toBe(OPENCODE_ZEN_CATALOG.length); + it("getLiveGoCatalog and getLiveZenCatalog return local shims, and a refresh replaces a plane's rows: what the registry no longer lists is gone", async () => { + expect(getLiveGoCatalog(answering({}, 503))).toHaveLength( + OPENCODE_GO_CATALOG.length + ); + expect(getLiveZenCatalog(answering({}, 503))).toHaveLength( + OPENCODE_ZEN_CATALOG.length + ); + const shimGo = OPENCODE_GO_CATALOG[0]?.id ?? ""; + expect(shimGo).not.toBe(""); - const mockFetch = vi.fn().mockResolvedValue( - Response.json({ - "opencode-go": { - models: { - "future-test-model": { - limit: { context: 1500000, output: 200000 }, - modalities: { input: ["text"] }, - name: "Future Test Model", - }, - "muse-spark-1.2-contributor": { - name: "Muse Spark 1.2 Contributor", - }, - }, + const result = await refreshCatalog( + answering( + payload({ + go: [{ id: "only-go", name: "Only Go" }], + zen: [{ id: "only-zen" }], + }) + ), + true + ); + + // Replaced, not merged: the base answered the shim's length plus one. + expect(liveIds("go")).toEqual(["only-go"]); + expect(liveIds("zen")).toEqual(["only-zen"]); + expect(findModelSpecOn("go", shimGo)).toBeUndefined(); + expect(result.go.map((model) => model.id)).toEqual(["only-go"]); + expect(result.go[0]?.name).toBe("Only Go"); + }); + + it("an id the registry retires leaves the live map on the refresh that retires it", async () => { + const shipped = shippedShimData(); + const shimGo = OPENCODE_GO_CATALOG[0]?.id ?? ""; + expect(OPENCODE_GO_CATALOG.length).toBeGreaterThan(1); + + await refreshCatalog( + answering(registryOf(shipped, { retire: { go: [shimGo] } })), + true + ); + + expect(findModelSpecOn("go", shimGo)).toBeUndefined(); + expect(isDeprecatedModelOn("go", shimGo)).toBe(true); + for (const row of OPENCODE_GO_CATALOG.slice(1)) { + expect(findModelSpecOn("go", row.id), row.id).toBeDefined(); + } + }); + + it("a parse moves nothing: the live retirements survive parsing another payload", async () => { + await refreshCatalog( + answering({ + opencode: { + models: { gone: { status: "deprecated" }, keep: { name: "K" } }, + }, + }), + true + ); + expect(isDeprecatedModelOn("zen", "gone")).toBe(true); + const generation = catalogGeneration(); + + parseModelsDevCatalog({ opencode: { models: { other: { name: "O" } } } }); + parseModelsDevCatalog({}); + + expect(isDeprecatedModelOn("zen", "gone")).toBe(true); + expect(findModelSpecOn("zen", "other")).toBeUndefined(); + expect(catalogGeneration()).toBe(generation); + }); + + it("the parse answers the retired ids it read, per plane, sorted", () => { + const parsed = parseModelsDevCatalog({ + opencode: { + models: { + b: { status: "deprecated" }, + live: { name: "Live" }, + a: { status: "deprecated" }, }, + }, + "opencode-go": { + models: { z: { status: "deprecated" }, live: { name: "Live" } }, + }, + }); + expect(parsed.deprecated).toEqual({ go: ["z"], zen: ["a", "b"] }); + for (const data of [null, {}, { "opencode-go": { models: "invalid" } }]) { + expect(parseModelsDevCatalog(data).deprecated).toEqual({ + go: [], + zen: [], + }); + } + }); + + it("L12: a failed or empty read replaces nothing, and a partial one replaces only the plane it carries", async () => { + const worldA = { + opencode: { + models: { za: { name: "ZA" }, zr: { status: "deprecated" } }, + }, + "opencode-go": { + models: { ga: { name: "GA" }, gr: { status: "deprecated" } }, + }, + }; + const landed = await refreshCatalog(answering(worldA), true); + expect(landed.ok).toBe(true); + + const NO_ACTIVE = "the registry's answer listed no active model"; + const failing: [string, typeof fetch, string | undefined][] = [ + [ + "a rejecting fetch", + (async () => { + throw new Error("offline"); + }) as unknown as typeof fetch, + "offline", + ], + ["a 503", answering({}, 503), "models.opencode.ai answered 503"], + [ + "a body that is not JSON", + (async () => new Response("not json")) as unknown as typeof fetch, + undefined, + ], + ["an empty registry", answering({}), NO_ACTIVE], + [ + "a registry of retired rows only", + answering({ opencode: { models: { x: { status: "deprecated" } } } }), + NO_ACTIVE, + ], + ]; + for (const [label, fetchFn, message] of failing) { + const generation = catalogGeneration(); + const result = await refreshCatalog(fetchFn, true); + expect(result.ok, label).toBe(false); + expect(liveIds("go"), label).toEqual(["ga"]); + expect(liveIds("zen"), label).toEqual(["za"]); + expect(isDeprecatedModelOn("zen", "zr"), label).toBe(true); + expect(isDeprecatedModelOn("zen", "x"), label).toBe(false); + expect(catalogGeneration(), label).toBe(generation); + expect(result.deprecated, label).toEqual({ go: ["gr"], zen: ["zr"] }); + if (message === undefined) { + // The JSON parser's own wording, which the engine owns. + expect(catalogLastError(), label).toBeDefined(); + expect(catalogLastError(), label).not.toBe(NO_ACTIVE); + } else { + expect(catalogLastError(), label).toBe(message); + } + } + + const partial = await refreshCatalog( + answering({ opencode: { models: { zb: { name: "B" } } } }), + true + ); + expect(partial.ok).toBe(true); + expect(liveIds("zen")).toEqual(["zb"]); + expect(isDeprecatedModelOn("zen", "zr")).toBe(false); + expect(liveIds("go")).toEqual(["ga"]); + // Zen's retirements from the payload (none), Go's held from world A. + expect(partial.deprecated).toEqual({ go: ["gr"], zen: [] }); + expect(catalogLastError()).toBe( + "the registry listed no active model for opencode-go" + ); + }); + + it("the refresh resolves { ok, deprecated } and keeps its last error with the state", async () => { + const full = await refreshCatalog( + answering({ opencode: { models: { - "future-zen-model": { - name: "Future Zen Model", - }, - "muse-spark-1.2": { - name: "Muse Spark 1.2", - }, + live: { name: "L" }, + zb: { status: "deprecated" }, + za: { status: "deprecated" }, }, }, - }) + "opencode-go": { + models: { g: { name: "G" }, gr: { status: "deprecated" } }, + }, + }), + true ); + expect(full.ok).toBe(true); + expect(full.deprecated).toEqual({ go: ["gr"], zen: ["za", "zb"] }); + expect(catalogLastError()).toBeUndefined(); - const updated = await refreshCatalog( - mockFetch as unknown as typeof fetch, + await refreshCatalog( + (async () => { + throw new Error("offline"); + }) as unknown as typeof fetch, true ); - expect(updated.go.length).toBe(OPENCODE_GO_CATALOG.length + 1); - // ONE zen row is new to the merged map: the mock's `future-zen-model`. Its - // `muse-spark-1.2` row is already in the regenerated shim, so it is not an - // addition. The parser's deprecation filter is the only filter, and the - // mock carries none, so nothing else can change the count. - expect(updated.zen.length).toBe(OPENCODE_ZEN_CATALOG.length + 1); - - const futureModel = updated.go.find((m) => m.id === "future-test-model"); - expect(futureModel).toBeDefined(); - expect(futureModel?.name).toBe("Future Test Model"); - expect(futureModel?.context_window).toBe(1500000); - expect(updated.go.some((m) => m.id === "muse-spark-1.2-contributor")).toBe( + expect(catalogLastError()).toContain("offline"); + + await refreshCatalog(answering({}, 503), true); + expect(catalogLastError()).toContain("503"); + + await refreshCatalog( + (async () => { + throw new Error("x".repeat(500)); + }) as unknown as typeof fetch, true ); - expect(updated.zen.some((m) => m.id === "muse-spark-1.2")).toBe(true); + expect(catalogLastError()).toBe("x".repeat(200)); + + await refreshCatalog( + answering(payload({ go: [{ id: "g" }], zen: [{ id: "z" }] })), + true + ); + expect(catalogLastError()).toBeUndefined(); + + await refreshCatalog(answering({}, 503), true); + expect(catalogLastError()).toBeDefined(); + resetCatalogState(); + expect(catalogLastError()).toBeUndefined(); + }); + + it("a refresh inside the TTL answers the state it holds without a read, and a thrown non-Error is named", async () => { + await refreshCatalog( + answering(payload({ go: [{ id: "g" }], zen: [{ id: "z" }] })), + true + ); + const unread = vi.fn(answering({}, 503)); + const cached = await refreshCatalog(unread); + expect(unread).not.toHaveBeenCalled(); + // Read nothing, and still `ok`: the state it reports is a landed read's + // (the field's doc says so). The purge never sees this answer: it forces. + expect(cached.ok).toBe(true); + expect(cached.go.map((model) => model.id)).toEqual(["g"]); + + await refreshCatalog( + (async () => { + // oxlint-disable-next-line no-throw-literal, typescript/only-throw-error -- the case is a fetch that throws something other than an Error. + throw "refused"; + }) as unknown as typeof fetch, + true + ); + expect(catalogLastError()).toBe("refused"); + }); + + it("an older attempt that fails after a newer forced one landed leaves no error behind", async () => { + // A background read on a cold start, slow and then failing... + let fail: (error: Error) => void = () => {}; + const slow = (() => + new Promise((_resolve, reject) => { + fail = reject; + })) as unknown as typeof fetch; + const background = refreshCatalog(slow); + // ...overtaken by the purge's forced read, which lands both planes. + const forced = await refreshCatalog( + answering(payload({ go: [{ id: "g" }], zen: [{ id: "z" }] })), + true + ); + expect(forced.ok).toBe(true); + expect(catalogLastError()).toBeUndefined(); + + fail(new Error("timed out")); + const late = await background; + + expect(late.ok).toBe(false); + expect(catalogLastError()).toBeUndefined(); + expect(liveIds("go")).toEqual(["g"]); + }); + + it("an older attempt that settles first leaves the newer one in flight, and a plain call joins it", async () => { + // A cold start (nothing landed, so no TTL answer): a background read and + // the purge's forced read, both still pending. + let fail: (error: Error) => void = () => {}; + const olderFetch = (() => + new Promise((_resolve, reject) => { + fail = reject; + })) as unknown as typeof fetch; + let land: (response: Response) => void = () => {}; + const newerFetch = (() => + new Promise((resolve) => { + land = resolve; + })) as unknown as typeof fetch; + const older = refreshCatalog(olderFetch); + const forced = refreshCatalog(newerFetch, true); + + // The older one settles first. It is not the newest, so it must not + // clear the in-flight promise the forced attempt owns. + fail(new Error("timed out")); + const settledOlder = await older; + expect(settledOlder.ok).toBe(false); + + const unread = vi.fn(answering({}, 503)); + const joined = refreshCatalog(unread); + expect(joined).toBe(forced); + expect(unread).not.toHaveBeenCalled(); + + land(Response.json(payload({ go: [{ id: "g" }], zen: [{ id: "z" }] }))); + const settledJoined = await joined; + expect(settledJoined.ok).toBe(true); + expect(unread).not.toHaveBeenCalled(); + }); + + it("an older attempt that lands both planes after a newer failure clears the error", async () => { + let land: (response: Response) => void = () => {}; + const slow = (() => + new Promise((resolve) => { + land = resolve; + })) as unknown as typeof fetch; + const older = refreshCatalog(slow); + await refreshCatalog(answering({}, 503), true); + expect(catalogLastError()).toBe("models.opencode.ai answered 503"); + land(Response.json(payload({ go: [{ id: "g" }], zen: [{ id: "z" }] }))); + const settled = await older; + expect(settled.ok).toBe(true); + // The state is now wholly that payload's, so the card must not say the + // last refresh failed beside it. + expect(liveIds("go")).toEqual(["g"]); + expect(catalogLastError()).toBeUndefined(); + }); + + it("an older attempt that lands one plane after a newer failure leaves the newer error", async () => { + let land: (response: Response) => void = () => {}; + const slow = (() => + new Promise((resolve) => { + land = resolve; + })) as unknown as typeof fetch; + const older = refreshCatalog(slow); + await refreshCatalog(answering({}, 503), true); + land(Response.json(payload({ go: [{ id: "g" }] }))); + const settled = await older; + expect(settled.ok).toBe(true); + // A partial landing writes no error of its own unless it is the newest, + // and it does not clear the newer one: Zen is still not the registry's. + expect(catalogLastError()).toBe("models.opencode.ai answered 503"); + }); + + it("the state starts from the shim's own retirements, read tolerantly", () => { + for (const value of [undefined, "x", { go: "x" }]) { + expect(deprecatedIdsOf(value)).toEqual({ go: [], zen: [] }); + } + expect(deprecatedIdsOf({ go: ["b", 1, "a"], zen: ["z"] })).toEqual({ + go: ["a", "b"], + zen: ["z"], + }); + resetCatalogState(); + // Over the shipped shim's own ids, which are none until it is regenerated + // with its retired ids: `purge-service`'s "a shim that carries retired + // ids…" plants the export and performs the seeding either way. + const shipped = shippedDeprecatedIds(); + for (const plane of ["go", "zen"] as const) { + for (const id of shipped[plane]) { + expect(isDeprecatedModelOn(plane, id), `${plane}: ${id}`).toBe(true); + } + } + for (const row of OPENCODE_GO_CATALOG) { + expect(isDeprecatedModelOn("go", row.id), row.id).toBe(false); + } + for (const row of OPENCODE_ZEN_CATALOG) { + expect(isDeprecatedModelOn("zen", row.id), row.id).toBe(false); + } }); it("refreshes from the OpenCode registry host, not a third-party mirror", async () => { diff --git a/test/generators.test.ts b/test/generators.test.ts index 3ea26df..d8162b3 100644 --- a/test/generators.test.ts +++ b/test/generators.test.ts @@ -24,7 +24,9 @@ * payload that reproduces the shim) exits 0. The limits generator's `--write` runs too, from a scratch * copy of `scripts/` and `src/` (its target is the `src/go-limits-data.ts` * beside its own folder): it rewrites current data in text that is not - * the renderer's, and writes a moved figure. The limits renderer's text is held to the committed file + * the renderer's, and writes a moved figure. The catalog generator's + * `--write` runs on such a copy too: it adds the retired ids, the copy then + * reads current, and its own runtime reader answers them. The limits renderer's text is held to the committed file * by the same render-and-format round trip the catalog renderer has. * * Every spawned script is offline: each reads `--from` or runs `--offline`, @@ -50,14 +52,13 @@ import { join } from "node:path"; import { describe, expect, it } from "vitest"; import { - render, + rewriteShim, shimData, type ShimData, shimStale, + shippedShim, splice, - spliceObject, - renderFamilyApi, - renderPlaneApi, + upsertObject, } from "../scripts/catalog-shim.ts"; import { canonical, @@ -73,7 +74,7 @@ import { inBand, low12, } from "../scripts/session-band.ts"; -import { payload } from "./support/catalogs.ts"; +import { payload, registryOf, shippedShimData } from "./support/catalogs.ts"; import { GO_MODEL_LIMITS, OPENCODE_FAMILY_API, @@ -87,12 +88,7 @@ import { const ROOT = join(import.meta.dirname, ".."); /** What the shim ships, in the shape the rule compares. */ -const SHIPPED: ShimData = { - familyApi: OPENCODE_FAMILY_API, - go: OPENCODE_GO_CATALOG, - planeApi: OPENCODE_PLANE_API, - zen: OPENCODE_ZEN_CATALOG, -}; +const SHIPPED: ShimData = shippedShimData(); /** A script under `scripts/`, run to completion by the Node running the suite. */ const runScript = ( @@ -169,52 +165,6 @@ const goLimitsDoc = ( ) .join("\n\n"); -/** - * A models.dev payload that reproduces `data`: every row with the fields the - * parser reads (its limits, cost, modalities and reasoning) and its family's - * endpoint as its own `provider.api`, each plane's endpoint as the provider's - * `api`, and a retired row for any family no live row names, so the family - * map is the shipped one. The inverse of `parseModelsDevCatalog` then - * `shimData`, which the current answers below hold. - */ -const shimPayload = (data: ShimData): Record => { - const provider = (plane: "go" | "zen"): Record => { - const families = data.familyApi[plane]; - const rows = data[plane]; - const models: Record = {}; - for (const row of rows) { - const npm = row.provider_npm ?? ""; - const api = families[npm]; - models[row.id] = { - ...(row.cost === undefined ? {} : { cost: row.cost }), - id: row.id, - limit: { context: row.context_window, output: row.max_output_tokens }, - modalities: { input: row.input_modalities }, - name: row.name, - provider: { - ...(api === undefined ? {} : { api }), - ...(npm === "" ? {} : { npm }), - }, - ...(row.reasoning === undefined ? {} : { reasoning: row.reasoning }), - ...(row.reasoning_options === undefined - ? {} - : { reasoning_options: row.reasoning_options }), - }; - } - const named = new Set(rows.map((row) => row.provider_npm ?? "")); - for (const [npm, api] of Object.entries(families)) { - if (!named.has(npm)) { - models[`retired-${npm || "default"}`] = { - provider: { api, ...(npm === "" ? {} : { npm }) }, - status: "deprecated", - }; - } - } - return { api: data.planeApi[plane], models }; - }; - return { "opencode-go": provider("go"), opencode: provider("zen") }; -}; - /** * {@link SHIPPED} with one family endpoint moved: the first Zen family the * shim names, to an address no vendor serves. @@ -268,7 +218,7 @@ describe("generators · one staleness rule", () => { // The payload the spawned cases feed reproduces the shim, and each moved // world differs from it in the endpoint alone, never in an id. const parsed = (data: ShimData): ShimData => - shimData(parseModelsDevCatalog(shimPayload(data))); + shimData(parseModelsDevCatalog(registryOf(data))); expect(shimStale(SHIPPED, parsed(SHIPPED))).toBe(false); expect(parsed(planeMoved())).toStrictEqual({ ...parsed(SHIPPED), @@ -339,31 +289,38 @@ describe("generators · one staleness rule", () => { }); it("the catalog renderer reproduces the shipped shim from its own data, as the nightly formats it", () => { - // `--write` on the shipped data, then the formatter the nightly runs: - // byte-identical, so a current shim proposes no refresh. + // `--write` on the shipped data (`rewriteShim`, the one function the + // script runs), then the formatter the nightly runs: byte-identical, so a + // current shim proposes no refresh. Until CI regenerates the shim it + // carries no retired-ids export, which `rewriteShim` adds: then the + // formatted text is the committed file plus that one block. const source = readFileSync(join(ROOT, "src", "catalog-data.ts"), "utf8"); const data = shimData({ api: OPENCODE_PLANE_API, + deprecated: SHIPPED.deprecated, familyApi: OPENCODE_FAMILY_API, go: OPENCODE_GO_CATALOG, zen: OPENCODE_ZEN_CATALOG, }); - let rewritten = splice(source, "OPENCODE_GO_CATALOG", render(data.go)); - rewritten = splice(rewritten, "OPENCODE_ZEN_CATALOG", render(data.zen)); - rewritten = spliceObject( - rewritten, - "OPENCODE_PLANE_API", - renderPlaneApi(data.planeApi) - ); - rewritten = spliceObject( - rewritten, - "OPENCODE_FAMILY_API", - renderFamilyApi(data.familyApi) - ); + const rewritten = rewriteShim(source, data); // Known answer: the renderer's own text is not the formatted file, so the // formatter below has work to do and the comparison is not vacuous. expect(rewritten).not.toBe(source); - expect(formatted("catalog-data.ts", rewritten)).toBe(source); + const shaped = formatted("catalog-data.ts", rewritten); + const carries = source.includes("export const OPENCODE_DEPRECATED_IDS: "); + if (carries) { + expect(shaped).toBe(source); + } else { + const start = shaped.lastIndexOf( + "/**", + shaped.indexOf("export const OPENCODE_DEPRECATED_IDS: ") + ); + const end = shaped.indexOf("export const OPENCODE_GO_CATALOG"); + expect(start).toBeGreaterThan(-1); + const block = shaped.slice(start, end); + expect(block).toContain(JSON.stringify(SHIPPED.deprecated.go)); + expect(`${shaped.slice(0, start)}${shaped.slice(end)}`).toBe(source); + } expect(() => splice(source, "NO_SUCH_EXPORT", "[]")).toThrow( /NO_SUCH_EXPORT/u ); @@ -387,6 +344,190 @@ describe("generators · one staleness rule", () => { }); }); +describe("generators · the retired ids are generated output", () => { + it("the parse carries them, and a shim that lacks one is stale", () => { + const firstZenId = OPENCODE_ZEN_CATALOG[0]?.id ?? ""; + expect(firstZenId).not.toBe(""); + const retired = shimData( + parseModelsDevCatalog( + registryOf(SHIPPED, { retire: { zen: [firstZenId] } }) + ) + ).deprecated.zen; + expect(retired).toContain(firstZenId); + expect(retired).toEqual(retired.toSorted()); + + const shippedRetired = SHIPPED.deprecated; + expect( + shimStale(SHIPPED, { + ...SHIPPED, + deprecated: { + go: shippedRetired.go, + zen: [...shippedRetired.zen, "made-up-retired"], + }, + }) + ).toBe(true); + const twoRetired = { + ...SHIPPED, + deprecated: { go: shippedRetired.go, zen: ["b-retired", "a-retired"] }, + }; + expect( + shimStale(twoRetired, { + ...twoRetired, + deprecated: { go: shippedRetired.go, zen: ["a-retired", "b-retired"] }, + }) + ).toBe(false); + const exports = { + OPENCODE_FAMILY_API, + OPENCODE_GO_CATALOG, + OPENCODE_PLANE_API, + OPENCODE_ZEN_CATALOG, + }; + expect(shippedShim(exports).deprecated).toEqual({ go: [], zen: [] }); + // Present, the export is read by its name, strings only, as written. + const carrying = shippedShim({ + ...exports, + OPENCODE_DEPRECATED_IDS: { go: ["b", "a"], zen: ["z", 1] }, + }); + expect(carrying.deprecated).toEqual({ go: ["b", "a"], zen: ["z"] }); + expect(carrying.go).toBe(OPENCODE_GO_CATALOG); + // The same ids in another order are current: order is not data. + expect( + shimStale(carrying, { + ...carrying, + deprecated: { go: ["a", "b"], zen: ["z"] }, + }) + ).toBe(false); + expect( + shimStale(carrying, { + ...carrying, + deprecated: { go: ["a"], zen: ["z"] }, + }) + ).toBe(true); + // Malformed, it is no retired id on either plane, never a throw. + for (const malformed of [null, "x", ["a"], { go: "a", zen: 3 }]) { + expect( + shippedShim({ ...exports, OPENCODE_DEPRECATED_IDS: malformed }) + .deprecated, + JSON.stringify(malformed) + ).toEqual({ go: [], zen: [] }); + } + }); + + it("the fixture payload never invents a retired id: a family nothing carries throws", () => { + const orphaned: ShimData = { + ...SHIPPED, + familyApi: { + ...SHIPPED.familyApi, + zen: { + ...SHIPPED.familyApi.zen, + "@ai-sdk/orphan": "https://x.invalid", + }, + }, + }; + expect(() => registryOf(orphaned)).toThrow(/@ai-sdk\/orphan/u); + // A retired id carries it, and the payload reproduces the data. + const carried = { + ...orphaned, + deprecated: { + go: SHIPPED.deprecated.go, + zen: [...SHIPPED.deprecated.zen, "carrier-retired"], + }, + }; + expect( + shimStale(carried, shimData(parseModelsDevCatalog(registryOf(carried)))) + ).toBe(false); + }); + + it("the generator adds the retired-ids export to a shim that has none, and rewrites it in place after", () => { + const fixture = [ + "/** A small shim. */", + 'import type { ModelCostRate } from "./session-cost.ts";', + "", + 'export const OPENCODE_PLANE_API: Readonly> = {', + ' go: "",', + ' zen: "",', + "};", + "", + "export const OPENCODE_FAMILY_API: Readonly<", + ' Record<"go" | "zen", Readonly>>', + "> = {", + " go: {},", + " zen: {},", + "};", + "", + "export const OPENCODE_GO_CATALOG: readonly CatalogModelSpec[] = [", + "];", + "", + "export const OPENCODE_ZEN_CATALOG: readonly CatalogModelSpec[] = [", + "];", + "", + ].join("\n"); + const data: ShimData = { + deprecated: { go: ["g-retired"], zen: [] }, + familyApi: { + go: { "@ai-sdk/anthropic": "https://example.invalid/go-family" }, + zen: {}, + }, + go: OPENCODE_GO_CATALOG.slice(0, 1), + planeApi: { + go: "https://example.invalid/go", + zen: "https://example.invalid/zen", + }, + // A row on each plane, so the formatted text keeps both array literals + // multi-line, as the real shim's are, for the second rewrite to read. + // Not the Go row's id, so a Go row rendered into Zen shows. + zen: OPENCODE_ZEN_CATALOG.filter( + (row) => row.id !== OPENCODE_GO_CATALOG[0]?.id + ).slice(0, 1), + }; + const declaration = "export const OPENCODE_DEPRECATED_IDS: "; + const once = rewriteShim(fixture, data); + expect(once.split(declaration)).toHaveLength(2); + expect(once.indexOf(declaration)).toBeLessThan( + once.indexOf("export const OPENCODE_GO_CATALOG") + ); + expect(once).toContain('"g-retired"'); + // Every other value the generator owns is written too, each in its own + // export: the plane and family endpoints, and the Go row in the Go + // catalog, not the Zen one. + expect(once).toContain('go: "https://example.invalid/go"'); + expect(once).toContain('zen: "https://example.invalid/zen"'); + expect(once).toContain('"https://example.invalid/go-family"'); + const goRow = `id: ${JSON.stringify(data.go[0]?.id)}`; + const goAt = once.indexOf("export const OPENCODE_GO_CATALOG"); + const zenAt = once.indexOf("export const OPENCODE_ZEN_CATALOG"); + expect(once.indexOf(goRow)).toBeGreaterThan(goAt); + expect(once.indexOf(goRow)).toBeLessThan(zenAt); + expect(once.slice(zenAt)).not.toContain(goRow); + // The new block follows a closed declaration, never splits a doc comment + // from its export: what precedes it is the family endpoints' `};`. + expect(once.slice(0, once.indexOf("/**", once.indexOf("> = {")))).toMatch( + /\};\n\n$/u + ); + // The renderer's text is formatter-stable once formatted. + const shaped = formatted("catalog-data.ts", once); + expect(formatted("catalog-data.ts", shaped)).toBe(shaped); + // The nightly's second run reads the FORMATTED file: the export is + // rewritten in place there, never added again. + const twice = rewriteShim(shaped, { + ...data, + deprecated: { go: [], zen: ["z-retired"] }, + }); + expect(twice.split(declaration)).toHaveLength(2); + expect(twice).toContain('"z-retired"'); + expect(twice).not.toContain('"g-retired"'); + expect(() => + upsertObject( + fixture, + "NEW_EXPORT", + "export const NEW_EXPORT = {};", + "{}", + "NO_SUCH_ANCHOR" + ) + ).toThrow(/NO_SUCH_ANCHOR/u); + }); +}); + describe("generators · the generators, spawned", () => { it("the limits generator answers current on a doc made from the shipped table, and stale when one figure moved", () => { const temp = mkdtempSync(join(tmpdir(), "go-limits-")); @@ -506,7 +647,7 @@ describe("generators · the generators, spawned", () => { // The known answer: a payload that reproduces the shim is current. const same = join(temp, "same.json"); - writeFileSync(same, JSON.stringify(shimPayload(SHIPPED))); + writeFileSync(same, JSON.stringify(registryOf(SHIPPED))); const current = runScript("regenerate-catalog-shim.ts", ["--from", same]); expect(current.status, current.stderr).toBe(0); expect(current.stdout).toContain("shim is current"); @@ -518,13 +659,37 @@ describe("generators · the generators, spawned", () => { ["family", familyMoved()], ] as const) { const path = join(temp, `${name}-moved.json`); - writeFileSync(path, JSON.stringify(shimPayload(moved))); + writeFileSync(path, JSON.stringify(registryOf(moved))); const run = runScript("regenerate-catalog-shim.ts", ["--from", path]); expect(run.status, `${name}: ${run.stderr}`).toBe(1); expect(run.stdout, name).toContain("shim is STALE"); expect(run.stdout, name).not.toMatch(/^ {2}[+-] /mu); } + // A retired id the shim does not hold is staleness too: the base read + // only the rows and endpoints, and called this current. + const retiring = join(temp, "retiring.json"); + const withRetired = registryOf(SHIPPED); + (withRetired.opencode as { models: Record }).models[ + "made-up-retired" + ] = { status: "deprecated" }; + writeFileSync(retiring, JSON.stringify(withRetired)); + const retiredRun = runScript("regenerate-catalog-shim.ts", [ + "--from", + retiring, + ]); + expect(retiredRun.status, retiredRun.stderr).toBe(1); + expect(retiredRun.stdout).toContain("shim is STALE"); + expect(retiredRun.stdout).toMatch( + /retired opencode\b.*\n {2}\+ 1: made-up-retired/u + ); + const retiredVerify = runScript("verify-catalog.ts", [ + "--from", + retiring, + ]); + expect(retiredVerify.status, retiredVerify.stdout).toBe(1); + expect(retiredVerify.stdout).toContain("shim is stale"); + const unread = runScript("regenerate-catalog-shim.ts", [ "--from", join(temp, "missing.json"), @@ -535,6 +700,60 @@ describe("generators · the generators, spawned", () => { rmSync(temp, { force: true, recursive: true }); } }); + + it("the catalog generator's --write adds the retired ids on a scratch copy, which then reads current and answers them at runtime", () => { + const temp = mkdtempSync(join(tmpdir(), "catalog-shim-write-")); + try { + // The generator's target is `../src/catalog-data.ts` from its own + // file, so a copy of both folders keeps the shipped file untouched. + for (const folder of ["scripts", "src"]) { + cpSync(join(ROOT, folder), join(temp, folder), { recursive: true }); + } + symlinkSync(join(ROOT, "node_modules"), join(temp, "node_modules")); + const node = (args: readonly string[]) => { + const run = spawnSync( + process.execPath, + [ + "--experimental-strip-types", + "--disable-warning=ExperimentalWarning", + ...args, + ], + { cwd: temp, encoding: "utf8", timeout: 60_000 } + ); + return { status: run.status, stderr: run.stderr, stdout: run.stdout }; + }; + const generator = join(temp, "scripts", "regenerate-catalog-shim.ts"); + const retiring = join(temp, "retiring.json"); + const world = registryOf(SHIPPED); + (world.opencode as { models: Record }).models[ + "made-up-retired" + ] = { status: "deprecated" }; + writeFileSync(retiring, JSON.stringify(world)); + + const write = node([generator, "--write", "--from", retiring]); + expect(write.status, write.stderr).toBe(0); + expect(write.stdout).toContain("wrote catalog-data.ts"); + const again = node([generator, "--from", retiring]); + expect(again.status, again.stderr).toBe(0); + expect(again.stdout).toContain("shim is current"); + + // The writer's export name is the runtime reader's. + const read = node([ + "--input-type=module", + "-e", + `const m = await import(${JSON.stringify( + join(temp, "src", "models-catalog.ts") + )}); console.log(JSON.stringify(m.shippedDeprecatedIds()));`, + ]); + expect(read.status, read.stderr).toBe(0); + expect(JSON.parse(read.stdout)).toEqual({ + go: SHIPPED.deprecated.go, + zen: [...SHIPPED.deprecated.zen, "made-up-retired"].toSorted(), + }); + } finally { + rmSync(temp, { force: true, recursive: true }); + } + }); }); describe("generators · verify-catalog fails closed", () => { @@ -557,7 +776,7 @@ describe("generators · verify-catalog fails closed", () => { // shim, and fails on the same ids with one endpoint moved, which the // old rule (id sets) called current. const same = join(temp, "same.json"); - writeFileSync(same, JSON.stringify(shimPayload(SHIPPED))); + writeFileSync(same, JSON.stringify(registryOf(SHIPPED))); const current = runScript("verify-catalog.ts", ["--from", same]); expect(current.status, current.stdout).toBe(0); expect(current.stdout).toMatch( @@ -569,7 +788,7 @@ describe("generators · verify-catalog fails closed", () => { ["family", familyMoved()], ] as const) { const path = join(temp, `${name}-moved.json`); - writeFileSync(path, JSON.stringify(shimPayload(moved))); + writeFileSync(path, JSON.stringify(registryOf(moved))); const run = runScript("verify-catalog.ts", ["--from", path]); expect(run.status, `${name}: ${run.stdout}`).toBe(1); expect(run.stdout, name).toContain("shim is stale"); diff --git a/test/host-planes-config.test.ts b/test/host-planes-config.test.ts index 2a2725c..aa7826c 100644 --- a/test/host-planes-config.test.ts +++ b/test/host-planes-config.test.ts @@ -7,7 +7,12 @@ import { readFileSync, writeFileSync } from "node:fs"; import { join } from "node:path"; +import { + readProfilePatches, + reconcileProfilePatches, +} from "@deepseek-ai/dsh-app-boot"; import { afterEach, describe, expect, it, vi } from "vitest"; +import { parse } from "yaml"; import { appendTo, @@ -231,3 +236,155 @@ describe("host planes · the route set (tier B)", { timeout: 30_000 }, () => { await waitForPlaneOwner(tier.llm, ["opencode"]); }); }); + +describe( + "host planes · removing what pi cannot serve, before the plugin goes (tier B)", + { timeout: 30_000 }, + () => { + /** An id no pi and no catalog describes, declared with no route `api`. */ + const UNSERVED = "not-a-real-model"; + + /** The purge service the plugin mounts on the root. */ + const purgeOf = ( + tier: TierB + ): { + readonly review: () => Promise<{ + readonly unserved: readonly { id: string; provider: string }[]; + readonly piRead: boolean; + }>; + readonly removeUnserved: () => Promise<{ + readonly removed: readonly { id: string; provider: string }[]; + }>; + } => tier.ctx.get("opencodeModelPurge") as never; + + /** + * The model ids the profile patch declares on `route`, read with the YAML + * parser: every `providers..models` the patch's rows carry. + */ + const declaredOn = (patch: string, route: string): string[] => { + const ids: string[] = []; + const walk = (value: unknown): void => { + if (Array.isArray(value)) { + for (const item of value) { + walk(item); + } + return; + } + if (typeof value !== "object" || value === null) { + return; + } + const record = value as Record; + const providers = record.providers as + | Record + | undefined; + const models = providers?.[route]?.models; + if (Array.isArray(models)) { + for (const model of models) { + ids.push( + typeof model === "string" ? model : (model as { id: string }).id + ); + } + } + for (const item of Object.values(record)) { + walk(item); + } + }; + walk(parse(patch)); + return ids; + }; + + /** Boot with `opencode` declaring a pi-known id and {@link UNSERVED}. */ + const boot = async (): Promise => { + const { deepseek, opencode } = s0Providers(); + const { tier } = await bootPlanes({ + providers: { + deepseek: deepseek ?? {}, + opencode: { + apiKeyEnv: opencode?.apiKeyEnv, + models: [{ id: "deepseek-v4-pro" }, { id: UNSERVED }], + }, + }, + }); + await waitForPlaneOwner(tier.llm, ["opencode"]); + await settle(); + return tier; + }; + + /** + * Remove the plugin the way a profile edit reaches a running host: its row + * disabled in the profile patch and the profile reloaded, so the loader + * disposes its fiber and pi-ai serves the plane again. + */ + const handBack = async (tier: TierB): Promise => { + const { pluginEntry } = tier; + if (pluginEntry === undefined) { + throw new Error("no plugin row"); + } + // YAML, not JSON: a config editor write leaves the patch in YAML, and + // JSON is YAML too, so one parser reads either. + const rows = parse( + readFileSync(tier.profile.patchPath, "utf8") + ) as unknown[]; + writeFileSync( + tier.profile.patchPath, + `${JSON.stringify([...rows, { disabled: true, id: pluginEntry.options.id }], null, 2)}\n` + ); + await reconcileProfilePatches( + tier.ctx as never, + readProfilePatches("dsh", tier.profile), + "dsh" + ); + await until( + () => pluginEntry.fiber === undefined || pluginEntry.fiber.uid === null, + "the plugin row is disposed" + ); + await waitForPlaneOwner(tier.llm, ["opencode"], "PiAiAdapter"); + await settle(); + }; + + it("the card's removal clears what pi cannot serve, in one write, and the handback's next Settings edit is then accepted", async () => { + const tier = await boot(); + const service = purgeOf(tier); + const review = await service.review(); + // Exactly the unknown id: `deepseek-v4-pro` is in pi's installed + // catalog on every cell, so a review or removal that over-lists (a + // lookup under the wrong route among them) fails here. + expect(review.piRead).toBe(true); + expect(review.unserved).toEqual([{ id: UNSERVED, provider: "opencode" }]); + + const edits = vi.spyOn(tier.ctx.configEditor, "edit"); + const before = readFileSync(tier.profile.patchPath, "utf8"); + const result = await service.removeUnserved(); + expect(result.removed).toEqual([{ id: UNSERVED, provider: "opencode" }]); + expect(edits).toHaveBeenCalledTimes(1); + const after = readFileSync(tier.profile.patchPath, "utf8"); + expect(after).not.toBe(before); + expect(after).not.toContain(UNSERVED); + expect(declaredOn(after, "opencode")).toEqual(["deepseek-v4-pro"]); + await until(async () => { + const listed = await tier.llm.listModels("opencode"); + return !listed.some((model) => model.id === UNSERVED); + }, "the removed id leaves the listing"); + edits.mockRestore(); + + await handBack(tier); + await expect( + tier.ctx.configEditor.edit( + tier.piEntry, + appendTo("opencode", "gpt-5.4") + ) + ).resolves.not.toThrow(); + }); + + it("the control: without the removal, the handback's next Settings edit is refused in pi-ai's words", async () => { + const tier = await boot(); + await handBack(tier); + await expect( + tier.ctx.configEditor.edit( + tier.piEntry, + appendTo("opencode", "gpt-5.4") + ) + ).rejects.toThrow(/needs an api/u); + }); + } +); diff --git a/test/host-planes-foreign.test.ts b/test/host-planes-foreign.test.ts index 83f9e88..2376977 100644 --- a/test/host-planes-foreign.test.ts +++ b/test/host-planes-foreign.test.ts @@ -22,6 +22,7 @@ import { readFileSync } from "node:fs"; import { afterEach, describe, expect, it, vi } from "vitest"; +import { registryOf, shippedShimData } from "./support/catalogs.ts"; import { effectiveConfigOf, sameFiber } from "./support/config-shape.ts"; import { adaptersOf, @@ -983,17 +984,21 @@ describe( /** An id the registry below retires on both planes; pi's catalog has never heard of it. */ const RETIRED = "retired-fixture-free"; - /** Answer the catalog read with `RETIRED` deprecated, and record the rest. */ + /** + * Answer the catalog read with the shipped world plus `RETIRED` deprecated + * on both planes, and record the rest. The shipped rows ride along: a + * plane lands only with an active row, and a payload of retired rows alone + * would land none. + */ const retiringRegistry = (): void => { wire = recordingFetch({ respond: (request) => request.url.startsWith("https://models.opencode.ai/") - ? Response.json({ - opencode: { models: { [RETIRED]: { status: "deprecated" } } }, - "opencode-go": { - models: { [RETIRED]: { status: "deprecated" } }, - }, - }) + ? Response.json( + registryOf(shippedShimData(), { + retire: { go: [RETIRED], zen: [RETIRED] }, + }) + ) : offlineAuthResponse(), }); vi.stubGlobal("fetch", wire.fetch); @@ -1221,17 +1226,18 @@ describe( }; /** - * A live catalog that retires {@link MODEL} on both planes: the plugin's - * merge drops a retired id from a plane it serves, so the id says whose - * answer Fetch gave. + * A live catalog that retires {@link MODEL} on both planes, the shipped + * rows beside it: the plugin's merge drops a retired id from a plane it + * serves, so the id says whose answer Fetch gave. */ const retireModel = async (): Promise => { await refreshCatalog( (async () => - Response.json({ - opencode: { models: { [MODEL]: { status: "deprecated" } } }, - "opencode-go": { models: { [MODEL]: { status: "deprecated" } } }, - })) as unknown as typeof fetch, + Response.json( + registryOf(shippedShimData(), { + retire: { go: [MODEL], zen: [MODEL] }, + }) + )) as unknown as typeof fetch, true ); }; diff --git a/test/models-discovery.test.ts b/test/models-discovery.test.ts index 59901b3..8b72319 100644 --- a/test/models-discovery.test.ts +++ b/test/models-discovery.test.ts @@ -16,6 +16,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"; +import { registryOf, shippedShimData } from "./support/catalogs.ts"; import { type CatalogModelSpec, complementDiscoveredModels, @@ -29,7 +30,6 @@ import { mergeDiscoveredModels, OPENCODE_GO_CATALOG, OPENCODE_ZEN_CATALOG, - parseModelsDevCatalog, type PlaneRoute, refreshCatalog, resolveConfig, @@ -169,24 +169,29 @@ describe("resolveDiscoveryProvider", () => { }); describe("mergeDiscoveredModels", () => { - it("drops an adapter row the registry has retired", () => { + it("drops an adapter row the registry has retired", async () => { // The adapter's installed snapshot is older than the live catalog and still // lists ids the vendor has retired — measured: 5 of pi's 85 opencode ids are // deprecated in the live catalog, and 6 live-active ids it lacks. Our own // catalog drops the retired ones during parse, so without this filter the // MERGE is what puts them back, and the picker leads with models that no - // longer answer. - parseModelsDevCatalog({ - opencode: { - api: "https://opencode.ai/zen/v1", - models: { - "still-here": { name: "Still Here" }, - "retired-one": { name: "Retired One", status: "deprecated" }, - }, - }, - }); + // longer answer. Seeded through the refresh: the parse is pure, and the + // refresh is what installs a payload's retirements. + await refreshCatalog( + (async () => + Response.json({ + opencode: { + api: "https://opencode.ai/zen/v1", + models: { + "still-here": { name: "Still Here" }, + "retired-one": { name: "Retired One", status: "deprecated" }, + }, + }, + })) as unknown as typeof fetch, + true + ); - // The parser saw the retirement… + // The refresh installed the retirement… expect(isDeprecatedModelOn("zen", "retired-one")).toBe(true); expect(isDeprecatedModelOn("zen", "still-here")).toBe(false); @@ -990,19 +995,21 @@ describe("complementDiscoveredModels", () => { it("a catalog model the registry retired since the shim, or whose SDK nothing serves, is not offered; pi's retired row is dropped too", async () => { const retired = servableIds(OPENCODE_ZEN_CATALOG)[0] ?? ""; expect(retired.length).toBeGreaterThan(0); + // The shipped Zen world with `retired` moved to retired and a row no SDK + // serves added: the refresh replaces the plane, so the payload carries + // every row the expectation below reads. await refreshCatalog( vi.fn().mockResolvedValue( - Response.json({ - opencode: { - models: { - [retired]: { status: "deprecated" }, - "cohere-x": { - name: "Cohere X", - provider: { npm: "@ai-sdk/cohere" }, - }, + Response.json( + registryOf(shippedShimData(), { + add: { + zen: [ + { id: "cohere-x", name: "Cohere X", sdk: "@ai-sdk/cohere" }, + ], }, - }, - }) + retire: { zen: [retired] }, + }) + ) ) as unknown as typeof fetch, true ); diff --git a/test/plane-lookup.test.ts b/test/plane-lookup.test.ts index d17f6bc..fda38ff 100644 --- a/test/plane-lookup.test.ts +++ b/test/plane-lookup.test.ts @@ -10,10 +10,10 @@ * the shipped one: a `models.dev` payload → the parser → the active maps → the * lookup. Nothing here reaches a synthetic consumer of the plugin's internals. * - * **The installation is per TEST.** `refreshCatalog` merges by id and cannot - * remove rows, but the suite's setup file (`test/support/reset-process-state.ts`) - * resets the live catalog after every test, so a world installed once per file - * would be gone by the second case. Installing before each one keeps every case + * **The installation is per TEST.** `refreshCatalog` replaces each plane the + * payload carries an active row for, and the suite's setup file + * (`test/support/reset-process-state.ts`) resets the live catalog after every + * test, so a world installed once per file would be gone by the second case. Installing before each one keeps every case * independent of the order it runs in; the rows still carry ids no other test * names. * diff --git a/test/plane-profile.test.ts b/test/plane-profile.test.ts index 060a3ba..23f1ebf 100644 --- a/test/plane-profile.test.ts +++ b/test/plane-profile.test.ts @@ -30,6 +30,7 @@ import { type PlanePiModel, planeEntriesOf, planeProfileFor, + piUnservedIds, withoutPlaneProviders, } from "./support/src.ts"; @@ -582,3 +583,55 @@ describe("plane-profile · withoutPlaneProviders and the plane readers", () => { expect(planeEntriesOf(raw, [])).toEqual({}); }); }); + +describe('piUnservedIds: pi-ai\'s "needs an api" rule, mirrored', () => { + const pi: readonly PlanePiModel[] = [ + { api: "a", id: "known" }, + { api: "b", id: "other" }, + ]; + const models = [ + { id: "known" }, + { id: "gap" }, + "bare-gap", + { name: "no id" }, + { id: "gap" }, + ]; + + it.each<[string, unknown, readonly PlanePiModel[], readonly string[]]>([ + [ + "each declared id pi lacks, once, in order", + { models }, + pi, + ["gap", "bare-gap"], + ], + [ + "a route api serves them all", + { api: "openai-completions", models }, + pi, + [], + ], + [ + "an empty route api is no api", + { api: "", models }, + pi, + ["gap", "bare-gap"], + ], + [ + "pi's models sharing one api serve them all", + { models }, + [{ api: "a", id: "known" }], + [], + ], + [ + "an empty pi catalog describes none", + { models }, + [], + ["known", "gap", "bare-gap"], + ], + ["no models", {}, pi, []], + ["models that is not a list", { models: "gap" }, pi, []], + ["an entry that is not a record", "opencode", pi, []], + ])("%s", (_label, entry, catalog, expected) => { + expect(piUnservedIds(entry, catalog)).toEqual(expected); + }); +}); diff --git a/test/purge-contract.test.ts b/test/purge-contract.test.ts index 0489f81..db692ef 100644 --- a/test/purge-contract.test.ts +++ b/test/purge-contract.test.ts @@ -9,7 +9,7 @@ */ import { describe, expect, it } from "vitest"; -import { parsePurgeResult } from "./support/src.ts"; +import { parsePurgeResult, parsePurgeReview } from "./support/src.ts"; describe("purge contract · the result codec", () => { it("accepts a result and keeps only the fields the card renders", () => { @@ -51,3 +51,45 @@ describe("purge contract · the result codec", () => { } }); }); + +describe("purge contract · the review codec", () => { + it("keeps only what the card renders", () => { + expect( + parsePurgeReview({ + catalogError: "e", + more: 1, + piRead: true, + unserved: [{ extra: 1, id: "a", provider: "opencode", site: "x" }], + }) + ).toEqual({ + catalogError: "e", + piRead: true, + unserved: [{ id: "a", provider: "opencode" }], + }); + expect( + parsePurgeReview({ + catalogError: "x".repeat(500), + piRead: false, + unserved: [], + })?.catalogError + ).toHaveLength(200); + expect( + parsePurgeReview({ catalogError: 7, piRead: false, unserved: [] }) + ).toEqual({ piRead: false, unserved: [] }); + }); + + it("rejects anything that is not a review", () => { + for (const value of [ + undefined, + null, + "review", + { unserved: [] }, + { piRead: "yes", unserved: [] }, + { piRead: true, unserved: "nope" }, + { piRead: true, unserved: [{ provider: "opencode" }] }, + { piRead: true, unserved: [{ id: 1, provider: "opencode" }] }, + ]) { + expect(parsePurgeReview(value), JSON.stringify(value)).toBeUndefined(); + } + }); +}); diff --git a/test/purge-service.test.ts b/test/purge-service.test.ts index fff7ec9..02cebca 100644 --- a/test/purge-service.test.ts +++ b/test/purge-service.test.ts @@ -2,9 +2,9 @@ * The purge action: it deletes the deployment's own declaration entries, and it * says which of the several ways it can refuse happened. * - * The catalog is the only source of "retired" — `extractSpecs` records a - * `status: "deprecated"` id and drops it from the active set — so these tests - * seed the module through the parser rather than inventing a second list. + * The catalog is the only source of "retired": the purge judges by the + * retired ids its own forced refresh answers (`CatalogRefresh.deprecated`), so + * each case stubs `fetch` with the registry it means and seeds nothing else. */ import { Context } from "@deepseek-ai/cordis"; import { afterEach, describe, expect, it, vi } from "vitest"; @@ -12,6 +12,9 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import { ModelPurgeService, parseModelsDevCatalog, + purgeEntryConfig, + refreshCatalog, + replaceHostModuleSource, stripRetiredReferences, } from "./support/src.ts"; @@ -81,7 +84,6 @@ afterEach(() => { describe("purge: deleting what the catalog retired", () => { it("removes the retired ids and leaves every live one", async () => { - parseModelsDevCatalog(registry()); answersRegistry(); const editor = editorWith({ zen: [{ id: "fledge-alpha-free" }, { id: "mimo-v2.6-flash-free" }], @@ -103,7 +105,6 @@ describe("purge: deleting what the catalog retired", () => { }); it("writes nothing when the deployment declares no retired model", async () => { - parseModelsDevCatalog(registry()); answersRegistry(); const editor = editorWith({ zen: [{ id: "mimo-v2.6-flash-free" }], @@ -116,18 +117,26 @@ describe("purge: deleting what the catalog retired", () => { expect(editor.entry.options.config.providers.opencode.models).toEqual([ { id: "mimo-v2.6-flash-free" }, ]); + // Not even a no-op write: on the real host one still validates, rewrites + // the profile document and reconciles. + expect(editor.edit).not.toHaveBeenCalled(); }); it("judges each plane route on its own plane: an id retired on Go only stays declared on Zen", async () => { // One id, live on Zen and retired on Go, declared on both routes. The // route-to-plane table decides which plane's retirement applies, so a - // swapped or constant plane fails one way or the other. + // swapped or constant plane fails one way or the other. Go carries a live + // row beside the retired one: a plane lands only with an active row (L12). const split = { opencode: { models: { "split-probe": { name: "Probe", limit: { context: 1000 } } }, }, - "opencode-go": { models: { "split-probe": { status: "deprecated" } } }, + "opencode-go": { + models: { + "go-live": { name: "Live" }, + "split-probe": { status: "deprecated" }, + }, + }, }; - parseModelsDevCatalog(split); vi.stubGlobal("fetch", () => Promise.resolve({ json: async () => split, ok: true }) ); @@ -179,16 +188,67 @@ describe("purge: the refusals it can report", () => { vi.stubGlobal("fetch", () => Promise.reject(new Error("offline"))); const { ModelPurgeService: Fresh } = await import("../src/purge-service.ts"); - const editor = editorWith({ - zen: [{ id: "mimo-v2.6-flash-free" }], - go: [], - }); + // A made-up id, so a regenerated shim's own retirements cannot touch it. + const editor = editorWith({ zen: [{ id: "offline-probe-model" }], go: [] }); const result = await new Fresh(ctxWith(editor)).purge(); expect(result.catalogRead).toBe(false); expect(result.removed).toEqual([]); }); + it("a shim that carries retired ids seeds a cold start with them, and an offline purge removes them", async () => { + // The shipped shim carries no `OPENCODE_DEPRECATED_IDS` until CI + // regenerates it, so the export is planted here: the runtime reader's + // export name, `shimState`'s seeding and the offline purge, performed. + vi.resetModules(); + vi.doMock("../src/catalog-data.ts", async (importOriginal) => ({ + ...(await importOriginal()), + OPENCODE_DEPRECATED_IDS: { + go: ["shim-retired-go"], + zen: ["shim-retired-zen", 7], + }, + })); + try { + vi.stubGlobal("fetch", () => Promise.reject(new Error("offline"))); + const catalog = await import("../src/models-catalog.ts"); + expect(catalog.shippedDeprecatedIds()).toEqual({ + go: ["shim-retired-go"], + zen: ["shim-retired-zen"], + }); + expect(catalog.isDeprecatedModelOn("go", "shim-retired-go")).toBe(true); + expect(catalog.isDeprecatedModelOn("zen", "shim-retired-zen")).toBe(true); + expect(catalog.isDeprecatedModelOn("zen", "shim-retired-go")).toBe(false); + const failed = await catalog.refreshCatalog(undefined, true); + expect(failed.ok).toBe(false); + expect(failed.deprecated).toEqual({ + go: ["shim-retired-go"], + zen: ["shim-retired-zen"], + }); + + const { ModelPurgeService: Fresh } = + await import("../src/purge-service.ts"); + const editor = editorWith({ + go: [{ id: "shim-retired-go" }, { id: "kept-go" }], + zen: [{ id: "shim-retired-zen" }], + }); + const result = await new Fresh(ctxWith(editor)).purge(); + expect(result).toEqual({ + catalogRead: false, + removed: [ + { id: "shim-retired-zen", provider: "opencode" }, + { id: "shim-retired-go", provider: "opencode-go" }, + ], + }); + expect(editor.edit).toHaveBeenCalledTimes(1); + expect( + editor.entry.options.config.providers["opencode-go"].models + ).toEqual([{ id: "kept-go" }]); + } finally { + vi.doUnmock("../src/catalog-data.ts"); + vi.resetModules(); + } + }); + it("reports nothing when the edit was rejected", async () => { // `configEditor.edit` throws after the change has been computed — "Profile // patch must be a YAML sequence" on a damaged document, "Configuration @@ -196,7 +256,12 @@ describe("purge: the refusals it can report", () => { // inside the callback meant those ids were reported as purged for an edit // that never landed. answersRegistry(); - const { entry } = editorWith({ zen: [{ id: "ll-alpha-free" }], go: [] }); + // A retired id, so the entry is judged to change and the edit is made: + // an entry with nothing retired is never edited at all. + const { entry } = editorWith({ + zen: [{ id: "fledge-alpha-free" }], + go: [], + }); const editor = { edit: vi.fn(() => Promise.reject(new Error("Profile patch must be a YAML sequence")) @@ -237,7 +302,6 @@ describe("purge: the refusals it can report", () => { describe("purge: the shapes a profile row can take", () => { it("skips a provider block with no models and a row with no id", async () => { - parseModelsDevCatalog(registry()); answersRegistry(); const entry = { options: { @@ -309,7 +373,6 @@ describe("purge: the shapes a config editor can take", () => { it("skips entries whose options chain is not shaped like a profile row", async () => { // Only one entry in a real loader has this shape; the rest must be walked // past without throwing. These are the intermediates the filter reads. - parseModelsDevCatalog(registry()); answersRegistry(); const declared = { options: { @@ -345,7 +408,6 @@ describe("purge: the shapes a config editor can take", () => { }); it("handles a provider block with no models array", async () => { - parseModelsDevCatalog(registry()); answersRegistry(); const entry = { options: { @@ -371,7 +433,6 @@ describe("purge: the shapes a config editor can take", () => { it("keeps a model row declared as a bare string", async () => { // The profile's rows are objects, but the schema also accepts a bare id. // A string row has no `id` field, so the reader must still name it. - parseModelsDevCatalog(registry()); answersRegistry(); const entry = { options: { @@ -421,7 +482,6 @@ describe("purge: references that are not provider declarations", () => { it("drops a subagent entry that names a retired model, and keeps the rest", async () => { // The shape that made the button lie: `allowedModels` declares no provider, // so the provider sweep never looked at it. - parseModelsDevCatalog(twoModelRegistry()); answers(twoModelRegistry()); const providerEntry = { options: { @@ -475,7 +535,6 @@ describe("purge: references that are not provider declarations", () => { it("clears the compaction summariser PAIR when its model was retired", async () => { // Leaving `summarizationProvider` behind would ask for a default model on a // named route; both keys go so the entry falls back to its own defaults. - parseModelsDevCatalog(twoModelRegistry()); answers(twoModelRegistry()); const providerEntry = { options: { @@ -516,7 +575,6 @@ describe("purge: references that are not provider declarations", () => { it("does not rewrite an entry with nothing to strip", async () => { // An unconditional edit would mark every entry dirty on every click. - parseModelsDevCatalog(twoModelRegistry()); answers(twoModelRegistry()); const providerEntry = { options: { @@ -539,10 +597,10 @@ describe("purge: references that are not provider declarations", () => { await new ModelPurgeService(ctxWith(editor)).purge(); - // The provider entry is edited once by the provider sweep (it decides inside - // the edit). The REFERENCE entry must not be touched at all — an - // unconditional edit would mark every entry dirty on every click. - expect(edit).toHaveBeenCalledTimes(1); + // Neither entry is touched: each is judged before its write, so an entry + // with nothing retired is never rewritten — an unconditional edit would + // mark every entry dirty on every click. + expect(edit).toHaveBeenCalledTimes(0); expect(JSON.stringify(untouched.options.config)).toBe(before); }); }); @@ -567,7 +625,6 @@ describe("purge: an entry another plugin owns is left to it (D27)", () => { const MARKER = { "x-opencode-plugin": "vendor/1.0.0" } as const; it("rewrites the unmarked plane and never the marked one beside it, nor a row in a realm the plugin does not share, nor a reference to a route only they declare", async () => { - parseModelsDevCatalog(registry()); answersRegistry(); // The user's own row: a marked `opencode` beside an unmarked `opencode-go`. const split = { @@ -637,7 +694,6 @@ describe("purge: an entry another plugin owns is left to it (D27)", () => { }); it("refuses, writing nothing, when every plane entry is another plugin's", async () => { - parseModelsDevCatalog(registry()); answersRegistry(); const marked = { options: { @@ -712,3 +768,594 @@ describe("purge: the pure reference stripper", () => { expect(removed).toEqual([]); }); }); + +describe("purge: one edit per entry, judged by its own read", () => { + /** An editor whose `edit` applies the change to the entry it is handed. */ + const applying = (entries: readonly unknown[]) => { + const edit = vi.fn( + async ( + entry: unknown, + change: (current: Record) => Record + ) => { + const holder = entry as { + options: { config: Record }; + }; + holder.options.config = change(holder.options.config); + } + ); + return { edit, entries: () => entries }; + }; + + const twoModelRegistry = () => ({ + opencode: { + models: { + "live-free": { name: "Live", limit: { context: 1_000 } }, + "retired-free": { status: "deprecated" }, + }, + }, + }); + + it("a retired declaration and two retired references in one entry are one write", async () => { + vi.stubGlobal("fetch", () => + Promise.resolve(Response.json(twoModelRegistry())) + ); + const entry = { + options: { + config: { + allowedModels: [{ model: "retired-free", provider: "opencode" }], + providers: { + opencode: { models: [{ id: "retired-free" }, { id: "live-free" }] }, + }, + summarizationModel: "retired-free", + summarizationProvider: "opencode", + }, + }, + }; + const editor = applying([entry]); + + const result = await new ModelPurgeService(ctxWith(editor)).purge(); + + expect(editor.edit).toHaveBeenCalledTimes(1); + expect(result.removed).toEqual([ + { id: "retired-free", provider: "opencode" }, + { id: "retired-free", provider: "opencode", site: "subagent" }, + { id: "retired-free", provider: "opencode", site: "summarizer" }, + ]); + expect(entry.options.config).toEqual({ + allowedModels: [], + providers: { opencode: { models: [{ id: "live-free" }] } }, + }); + }); + + it("an entry with nothing retired is not edited", async () => { + vi.stubGlobal("fetch", () => + Promise.resolve(Response.json(twoModelRegistry())) + ); + const editor = applying([ + { + options: { + config: { + providers: { opencode: { models: [{ id: "live-free" }] } }, + }, + }, + }, + { + options: { + config: { + allowedModels: [{ model: "live-free", provider: "opencode" }], + }, + }, + }, + ]); + + const result = await new ModelPurgeService(ctxWith(editor)).purge(); + + expect(editor.edit).not.toHaveBeenCalled(); + expect(result.removed).toEqual([]); + }); + + it("a parse made while the purge runs does not change what it removes", async () => { + vi.stubGlobal("fetch", () => + Promise.resolve(Response.json(twoModelRegistry())) + ); + const entry = { + options: { + config: { + providers: { + opencode: { models: [{ id: "retired-free" }, { id: "live-free" }] }, + }, + }, + }, + }; + const editor = applying([entry]); + const { entries } = editor; + editor.entries = () => { + // Any parse — a generator, an e2e file — used to clear the live + // retirements the purge was about to judge by. + parseModelsDevCatalog({ opencode: { models: { x: { name: "x" } } } }); + return entries(); + }; + + const result = await new ModelPurgeService(ctxWith(editor)).purge(); + + expect(result.removed).toEqual([ + { id: "retired-free", provider: "opencode" }, + ]); + expect(result.catalogRead).toBe(true); + }); + + it("a read that fails is judged by what the process already holds, and says the catalog was not read", async () => { + await refreshCatalog( + async () => + Response.json({ + opencode: { + models: { "r-free": { status: "deprecated" }, "z-live": {} }, + }, + }), + true + ); + vi.stubGlobal("fetch", () => Promise.reject(new Error("offline"))); + const editor = editorWith({ + zen: [{ id: "r-free" }, { id: "z-live" }], + go: [], + }); + + const result = await new ModelPurgeService(ctxWith(editor)).purge(); + + expect(result.removed).toEqual([{ id: "r-free", provider: "opencode" }]); + expect(result.catalogRead).toBe(false); + }); +}); + +describe("purge: an entry that changed between the judgement and its write", () => { + it("writes what the editor hands the change, and reports only what that removed", async () => { + vi.stubGlobal("fetch", () => + Promise.resolve( + Response.json({ + opencode: { + models: { + "live-free": { name: "Live" }, + "retired-free": { status: "deprecated" }, + }, + }, + }) + ) + ); + const entry = { + options: { + config: { + providers: { opencode: { models: [{ id: "retired-free" }] } }, + }, + }, + }; + // A reload between the pre-check and the write: the config the editor + // hands the change no longer declares the retired id. + let written: unknown; + const edit = vi.fn( + async ( + _entry: unknown, + change: (current: Record) => Record + ) => { + written = change({ + providers: { opencode: { models: [{ id: "live-free" }] } }, + }); + } + ); + + const result = await new ModelPurgeService( + ctxWith({ edit, entries: () => [entry] }) + ).purge(); + + expect(edit).toHaveBeenCalledTimes(1); + expect(written).toEqual({ + providers: { opencode: { models: [{ id: "live-free" }] } }, + }); + expect(result.removed).toEqual([]); + }); +}); + +describe("purge: the pure rewrite of one entry (purgeEntryConfig)", () => { + const retired = (_route: string, id: string): boolean => + id === "retired-free"; + + it("answers the config itself when nothing is retired", () => { + const config = { + allowedModels: [{ model: "live", provider: "opencode" }], + providers: { opencode: { models: [{ id: "live" }] } }, + }; + const { next, removed } = purgeEntryConfig(config, ["opencode"], retired); + expect(next).toBe(config); + expect(removed).toEqual([]); + }); + + it("filters only the routes it owns, declarations before references", () => { + const config = { + allowedModels: [{ model: "retired-free", provider: "opencode-go" }], + providers: { + opencode: { models: [{ id: "retired-free" }] }, + "opencode-go": { + api: "x", + models: ["retired-free", { name: "no id" }, { id: "live" }], + }, + }, + }; + const { next, removed } = purgeEntryConfig( + config, + ["opencode-go"], + retired + ); + expect(removed).toEqual([ + { id: "retired-free", provider: "opencode-go" }, + { id: "retired-free", provider: "opencode-go", site: "subagent" }, + ]); + expect(next).toEqual({ + allowedModels: [], + providers: { + opencode: { models: [{ id: "retired-free" }] }, + "opencode-go": { + api: "x", + models: [{ name: "no id" }, { id: "live" }], + }, + }, + }); + // The input is not mutated. + expect(config.providers["opencode-go"].models).toHaveLength(3); + }); + + it("reads past an owned route whose block is not a record", () => { + const config = { providers: { opencode: "not a block" } }; + expect(purgeEntryConfig(config, ["opencode"], retired).next).toBe(config); + }); + + it("reads past a provider block with no models and a providers value that is not a dict", () => { + const bare = { providers: { opencode: { api: "x" } } }; + expect(purgeEntryConfig(bare, ["opencode"], retired).next).toBe(bare); + const odd = { providers: "nope" }; + expect(purgeEntryConfig(odd, ["opencode"], retired).next).toBe(odd); + }); +}); + +describe("purge: the ids pi cannot serve (review and removeUnserved)", () => { + /** The routes the service asked pi's installed catalog for, in order. */ + const asked: string[] = []; + + /** + * Hand the service a pi whose installed catalog is `models` per route, or + * none. Each route answers its own list, and a route it does not hold + * answers none, so a lookup under the wrong key judges every declared id + * unserved and over-lists. + */ + const piCatalog = ( + models?: Readonly> + ): (() => void) => { + asked.length = 0; + return replaceHostModuleSource({ + libraries: async () => + models === undefined + ? undefined + : ({ + builtinModels: (route: string) => { + asked.push(route); + return models[route] ?? []; + }, + } as never), + piAi: async () => {}, + }); + }; + + const PI = { + opencode: [ + { api: "a", id: "known" }, + { api: "b", id: "other" }, + ], + "opencode-go": [ + { api: "a", id: "go-known" }, + { api: "b", id: "go-other" }, + ], + }; + + const MARKER = { "x-opencode-plugin": "vendor/1.0.0" } as const; + + /** An editor whose `edit` applies the change to the entry it is handed. */ + const applying = (entries: readonly unknown[]) => { + const edit = vi.fn( + async ( + entry: unknown, + change: (current: Record) => Record + ) => { + const holder = entry as { + options: { config: Record }; + }; + holder.options.config = change(holder.options.config); + } + ); + return { edit, entries: () => entries }; + }; + + const declaring = (providers: Record) => ({ + options: { config: { providers }, id: "llm-pi-ai" }, + }); + + it("review lists the declared ids pi cannot serve, per owned route, and writes nothing", async () => { + const restore = piCatalog(PI); + const fetchSpy = vi.fn(() => Promise.reject(new Error("no network"))); + vi.stubGlobal("fetch", fetchSpy); + try { + const editor = applying([ + declaring({ + opencode: { models: [{ id: "known" }, { id: "gap-1" }] }, + "opencode-go": { models: ["go-known", "gap-2", "known"] }, + }), + // Another plugin's entry (D27): its ids are not listed. + declaring({ + opencode: { + headers: { "x-opencode-plugin": "vendor/1.0.0" }, + models: [{ id: "theirs" }], + }, + }), + ]); + const review = await new ModelPurgeService(ctxWith(editor)).review(); + // Each route judged by its own list: `known` is pi's on `opencode` + // only, so it is listed on `opencode-go`, and `go-known` is not. + expect(review).toEqual({ + piRead: true, + unserved: [ + { id: "gap-1", provider: "opencode" }, + { id: "gap-2", provider: "opencode-go" }, + { id: "known", provider: "opencode-go" }, + ], + }); + expect(asked).toEqual(["opencode", "opencode-go"]); + expect(editor.edit).not.toHaveBeenCalled(); + expect(fetchSpy).not.toHaveBeenCalled(); + } finally { + restore(); + } + }); + + it("review says when pi's catalog could not be read, and carries the catalog's last error", async () => { + const restore = piCatalog(); + try { + vi.stubGlobal("fetch", () => Promise.reject(new Error("offline"))); + await refreshCatalog(undefined, true); + const editor = applying([ + declaring({ opencode: { models: [{ id: "gap-1" }] } }), + ]); + const review = await new ModelPurgeService(ctxWith(editor)).review(); + expect(review.piRead).toBe(false); + expect(review.unserved).toEqual([]); + expect(review.catalogError).toContain("offline"); + } finally { + restore(); + } + }); + + it("review reads a pi whose libraries throw as unread", async () => { + const restore = replaceHostModuleSource({ + libraries: () => Promise.reject(new Error("no pi here")), + piAi: async () => {}, + }); + try { + const editor = applying([ + declaring({ opencode: { models: [{ id: "gap-1" }] } }), + ]); + await expect( + new ModelPurgeService(ctxWith(editor)).review() + ).resolves.toEqual({ piRead: false, unserved: [] }); + } finally { + restore(); + } + }); + + it("review answers the catalog's last error when no plane entry is the plugin's, and lists nothing", async () => { + const restore = piCatalog(PI); + try { + vi.stubGlobal("fetch", () => Promise.reject(new Error("offline"))); + await refreshCatalog(undefined, true); + const profiles: [string, unknown[]][] = [ + ["no plane entry", [{ options: { config: { other: 1 } } }]], + [ + "only another plugin's", + [ + declaring({ + opencode: { headers: { ...MARKER }, models: [{ id: "gap-1" }] }, + }), + ], + ], + ]; + for (const [label, entries] of profiles) { + const editor = applying(entries); + // oxlint-disable-next-line no-await-in-loop -- one profile at a time. + const review = await new ModelPurgeService(ctxWith(editor)).review(); + expect(review.piRead, label).toBe(true); + expect(review.unserved, label).toEqual([]); + expect(review.catalogError, label).toContain("offline"); + expect(editor.edit, label).not.toHaveBeenCalled(); + } + } finally { + restore(); + } + // The same profile with pi unreadable says so, and still carries the error. + const unread = piCatalog(); + try { + const review = await new ModelPurgeService( + ctxWith(applying([{ options: { config: {} } }])) + ).review(); + expect(review).toMatchObject({ piRead: false, unserved: [] }); + expect(review.catalogError).toContain("offline"); + } finally { + unread(); + } + }); + + it("review refuses with no editor, as the purge does", async () => { + await expect( + new ModelPurgeService(ctxWith(undefined)).review() + ).rejects.toMatchObject({ code: "opencode/purge-unavailable" }); + }); + + it("removeUnserved removes those ids and references to them, one edit per entry, with no catalog read", async () => { + const restore = piCatalog(PI); + const fetchSpy = vi.fn(() => Promise.reject(new Error("no network"))); + vi.stubGlobal("fetch", fetchSpy); + try { + const a = declaring({ + opencode: { models: [{ id: "known" }, { id: "gap-1" }] }, + }); + const b = { + options: { + config: { + allowedModels: [ + { model: "gap-1", provider: "opencode" }, + { model: "known", provider: "opencode" }, + ], + }, + }, + }; + const c = { + options: { + config: { + summarizationModel: "known", + summarizationProvider: "opencode", + }, + }, + }; + const cBefore = structuredClone(c.options.config); + const editor = applying([a, b, c]); + + const result = await new ModelPurgeService( + ctxWith(editor) + ).removeUnserved(); + + expect(result).toEqual({ + catalogRead: true, + removed: [ + { id: "gap-1", provider: "opencode" }, + { id: "gap-1", provider: "opencode", site: "subagent" }, + ], + }); + expect(editor.edit).toHaveBeenCalledTimes(2); + expect(editor.edit.mock.calls.map(([entry]) => entry)).toEqual([a, b]); + expect(c.options.config).toEqual(cBefore); + expect(fetchSpy).not.toHaveBeenCalled(); + } finally { + restore(); + } + }); + + it("removeUnserved judges each entry's declarations by its own block, and review lists an id two entries declare once", async () => { + const restore = piCatalog(PI); + try { + const a = declaring({ + opencode: { models: [{ id: "known" }, { id: "gap-1" }] }, + }); + // A route-level `api`: pi-ai serves every id on it, so it lists none + // and keeps `gap-1`, which `a` and `c` cannot serve. + const b = declaring({ + opencode: { api: "openai-completions", models: [{ id: "gap-1" }] }, + }); + const c = declaring({ opencode: { models: ["gap-1"] } }); + // The subagent's reference goes although `b` keeps `gap-1`: three owned + // entries on one route is a composition the host's registry refuses + // (DUPLICATE_ADAPTER), so which one serves `opencode` once the plugin + // is gone depends on apply order, and a reference, which names a route + // and not an entry, is judged route-wide. + const subagent = { + options: { + config: { allowedModels: [{ model: "gap-1", provider: "opencode" }] }, + }, + }; + const bBefore = structuredClone(b.options.config); + const editor = applying([a, b, c, subagent]); + const service = new ModelPurgeService(ctxWith(editor)); + + await expect(service.review()).resolves.toEqual({ + piRead: true, + unserved: [{ id: "gap-1", provider: "opencode" }], + }); + + const result = await service.removeUnserved(); + + expect(result).toEqual({ + catalogRead: true, + removed: [ + { id: "gap-1", provider: "opencode" }, + { id: "gap-1", provider: "opencode" }, + { id: "gap-1", provider: "opencode", site: "subagent" }, + ], + }); + expect(editor.edit.mock.calls.map(([entry]) => entry)).toEqual([ + a, + c, + subagent, + ]); + expect(b.options.config).toEqual(bBefore); + expect(a.options.config.providers).toEqual({ + opencode: { models: [{ id: "known" }] }, + }); + } finally { + restore(); + } + }); + + it("removeUnserved leaves another plugin's entry and a reference to a route only it declares alone (D27)", async () => { + const restore = piCatalog(PI); + try { + const marked = declaring({ + opencode: { headers: { ...MARKER }, models: [{ id: "gap-1" }] }, + }); + const owned = declaring({ "opencode-go": { models: [{ id: "gap-1" }] } }); + const subagent = { + options: { + config: { + allowedModels: [ + { model: "gap-1", provider: "opencode" }, + { model: "gap-1", provider: "opencode-go" }, + ], + }, + }, + }; + const markedBefore = structuredClone(marked.options.config); + const editor = applying([marked, owned, subagent]); + + const result = await new ModelPurgeService( + ctxWith(editor) + ).removeUnserved(); + + expect(result).toEqual({ + catalogRead: true, + removed: [ + { id: "gap-1", provider: "opencode-go" }, + { id: "gap-1", provider: "opencode-go", site: "subagent" }, + ], + }); + expect(marked.options.config).toEqual(markedBefore); + expect(editor.edit.mock.calls.map(([entry]) => entry)).toEqual([ + owned, + subagent, + ]); + expect(subagent.options.config.allowedModels).toEqual([ + { model: "gap-1", provider: "opencode" }, + ]); + expect(asked).toEqual(["opencode-go"]); + } finally { + restore(); + } + }); + + it("removeUnserved removes nothing when pi's catalog cannot be read", async () => { + const restore = piCatalog(); + try { + const editor = applying([ + declaring({ opencode: { models: [{ id: "gap-1" }] } }), + ]); + const result = await new ModelPurgeService( + ctxWith(editor) + ).removeUnserved(); + expect(result).toEqual({ catalogRead: false, removed: [] }); + expect(editor.edit).not.toHaveBeenCalled(); + } finally { + restore(); + } + }); +}); diff --git a/test/remote-contract.test.ts b/test/remote-contract.test.ts index cdd6781..cbb44e9 100644 --- a/test/remote-contract.test.ts +++ b/test/remote-contract.test.ts @@ -28,6 +28,7 @@ import { OpencodeStoreService, parseAccountRef, parsePurgeResult, + parsePurgeReview, parseStoreInspection, parseUsageQuery, parseUsageReading, @@ -274,6 +275,24 @@ describe("remote contract · the wire, pinned field for field", () => { result: "dsh-opencode-patch#PurgeResult", service: "opencodeModelPurge", }, + { + id: "dsh-opencode-patch#opencodeModelPurge/review", + invocation: { kind: "direct" }, + method: "review", + namespace: "opencodeModelPurge", + parameters: [], + result: "dsh-opencode-patch#PurgeReview", + service: "opencodeModelPurge", + }, + { + id: "dsh-opencode-patch#opencodeModelPurge/removeUnserved", + invocation: { kind: "direct" }, + method: "removeUnserved", + namespace: "opencodeModelPurge", + parameters: [], + result: "dsh-opencode-patch#PurgeResult", + service: "opencodeModelPurge", + }, { id: "dsh-opencode-patch#opencodeStore/inspect", invocation: { kind: "direct" }, @@ -311,7 +330,8 @@ describe("remote contract · the wire, pinned field for field", () => { expect(codec.mode).toBe("strict"); } } - const [read, readAccount, purge, inspect] = descriptors; + const [read, readAccount, purge, review, removeUnserved, inspect] = + descriptors; expect(Object.keys(readAccount?.parameters[0] ?? {}).toSorted()).toEqual([ "codec", "name", @@ -328,12 +348,17 @@ describe("remote contract · the wire, pinned field for field", () => { parseAccountRef ); expect(purge?.result.schema.parse).toBe(parsePurgeResult); + expect(review?.result.schema.parse).toBe(parsePurgeReview); + expect(removeUnserved?.result).toBe(purge?.result); expect(inspect?.result.schema.parse).toBe(parseStoreInspection); }); it.each([ { methods: ["read", "readAccount"], Service: GoUsageService }, - { methods: ["purge"], Service: ModelPurgeService }, + { + methods: ["purge", "review", "removeUnserved"], + Service: ModelPurgeService, + }, { methods: ["inspect"], Service: OpencodeStoreService }, ])( "pins the Remote marker $Service.name carries, as the host's reader sees it", diff --git a/test/remote-seam.test.ts b/test/remote-seam.test.ts index 4bd83b7..d689151 100644 --- a/test/remote-seam.test.ts +++ b/test/remote-seam.test.ts @@ -34,10 +34,13 @@ import { OpencodeStoreService, ModelPurgeService, parseFailure, - parseModelsDevCatalog, purgeDeprecatedModels, readGoUsage, recordTurnUsage, + refreshCatalog, + removeUnservedModels, + replaceHostModuleSource, + reviewPurge, } from "./support/src.ts"; import { okBody, @@ -255,7 +258,6 @@ describe("remote seam · purge: a result and the host's refusal reach the card a }); it("carries the service's result, with every site it reports", async () => { - parseModelsDevCatalog(registry); vi.stubGlobal("fetch", async () => ({ json: async () => registry, ok: true, @@ -319,3 +321,108 @@ describe("remote seam · purge: a result and the host's refusal reach the card a }); }); }); + +describe("remote seam · the ids pi cannot serve: the service's review and removal reach the card whole", () => { + /** A pi whose installed catalog knows `known` on both plane routes. */ + const piKnowing = (): (() => void) => + replaceHostModuleSource({ + libraries: async () => + ({ + builtinModels: () => [ + { api: "openai-completions", id: "known" }, + { api: "anthropic-messages", id: "other" }, + ], + }) as never, + piAi: async () => {}, + }); + + /** A context whose config editor declares one gap per route and a reference. */ + const declaring = (): Context => { + const entries = [ + { + options: { + config: { + providers: { + opencode: { models: [{ id: "known" }, { id: "gap-1" }] }, + "opencode-go": { models: ["gap-2"] }, + }, + }, + }, + }, + { + options: { + config: { + allowedModels: [{ model: "gap-1", provider: "opencode" }], + }, + }, + }, + ]; + const ctx = new Context(); + ctx.provide( + "configEditor" as never, + { + edit: async ( + entry: unknown, + change: (current: Record) => Record + ) => { + const holder = entry as { + options: { config: Record }; + }; + holder.options.config = change(holder.options.config); + }, + entries: () => entries, + } as never + ); + return ctx; + }; + + it("carries a review with rows and the catalog's last error", async () => { + const restore = piKnowing(); + try { + vi.stubGlobal("fetch", () => Promise.reject(new Error("offline"))); + await refreshCatalog(undefined, true); + const answer = await new ModelPurgeService(declaring()).review(); + // Every field the card reads is set, so a parser that drops one fails. + expect(answer.piRead).toBe(true); + expect(answer.unserved).toHaveLength(2); + expect(answer.catalogError).toContain("offline"); + await expect( + reviewPurge({ + remote: { + opencodeModelPurge: { + review: async () => ({ ok: true, value: overTheWire(answer) }), + }, + }, + }) + ).resolves.toEqual({ kind: "review", review: overTheWire(answer) }); + } finally { + restore(); + } + }); + + it("carries a removal with every site it reports", async () => { + const restore = piKnowing(); + try { + const result = await new ModelPurgeService(declaring()).removeUnserved(); + expect(result.removed.map((row) => row.site)).toEqual([ + undefined, + undefined, + "subagent", + ]); + await expect( + removeUnservedModels({ + remote: { + opencodeModelPurge: { + removeUnserved: async () => ({ + ok: true, + value: overTheWire(result), + }), + }, + }, + }) + ).resolves.toEqual({ kind: "purged", result: overTheWire(result) }); + } finally { + restore(); + } + }); +}); diff --git a/test/settings-card-purge.test.tsx b/test/settings-card-purge.test.tsx index 500ea34..d795378 100644 --- a/test/settings-card-purge.test.tsx +++ b/test/settings-card-purge.test.tsx @@ -15,7 +15,12 @@ import { describe, expect, it, vi } from "vitest"; globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean } ).IS_REACT_ACT_ENVIRONMENT = true; -import { OpencodeCard, purgeLine } from "../src/settings-card.tsx"; +import { + OpencodeCard, + purgeLine, + reviewLines, + unservedLine, +} from "../src/settings-card.tsx"; import { en } from "../src/settings-copy.ts"; /** @@ -363,3 +368,331 @@ describe("settings-card: the states that only exist after an interaction", () => } }); }); + +describe("settings-card: the ids pi cannot serve, beside the purge row", () => { + const t = (key: string): string => key; + + it("says what the review found, grouped by provider in first-seen order", () => { + expect( + reviewLines(t, { + catalogError: "offline", + piRead: true, + unserved: [ + { id: "a", provider: "opencode" }, + { id: "c", provider: "opencode-go" }, + { id: "b", provider: "opencode" }, + ], + }) + ).toEqual({ + error: "catalogLastError: offline", + unserved: "opencode: a, b · opencode-go: c", + }); + expect(reviewLines(t, { piRead: true, unserved: [] })).toEqual({}); + // A review that could not read pi lists nothing, and says so. + expect(reviewLines(t, { piRead: false, unserved: [] })).toEqual({ + piUnread: "unservedPiUnreadReview", + }); + }); + + it("says what one removal did", () => { + expect( + unservedLine(t, { + kind: "purged", + result: { + catalogRead: true, + removed: [{ id: "a", provider: "opencode" }], + }, + }) + ).toEqual({ line: "1 unservedRemoved", warn: false }); + expect( + unservedLine(t, { + kind: "purged", + result: { catalogRead: true, removed: [] }, + }) + ).toEqual({ line: "unservedNothing", warn: false }); + expect( + unservedLine(t, { + kind: "purged", + result: { catalogRead: false, removed: [] }, + }) + ).toEqual({ line: "unservedPiUnread", warn: true }); + expect(unservedLine(t, { kind: "failed", message: "boom" })).toEqual({ + line: "purgeFailed: boom", + warn: true, + }); + expect(unservedLine(t, { kind: "unavailable" })).toEqual({ + line: "purgeUnavailable", + warn: true, + }); + }); + + const mount = async (extra: Record) => { + const { act } = await import("react"); + const { createRoot } = await import("react-dom/client"); + const host = document.createElement("div"); + document.body.append(host); + const root = createRoot(host); + const settle = async (): Promise => { + await act(async () => { + await new Promise((resolve) => { + setTimeout(resolve, 0); + }); + }); + }; + const render = (next: Record): void => { + act(() => { + root.render(createElement(OpencodeCard, props(next) as never)); + }); + }; + render(extra); + await settle(); + const cleanup = (): void => { + act(() => { + root.unmount(); + }); + host.remove(); + }; + const button = (label: string) => + [...host.querySelectorAll("button")].find((b) => + (b.textContent ?? "").includes(label) + ); + return { act, button, cleanup, host, render, settle }; + }; + + /** A review answer listing `ids` on `opencode`. */ + const listing = (...ids: string[]) => ({ + kind: "review", + review: { + piRead: true, + unserved: ids.map((id) => ({ id, provider: "opencode" })), + }, + }); + + const purgeDeprecated = async () => ({ + kind: "purged", + result: { catalogRead: true, removed: [] }, + }); + + it("lists the ids and removes them on request, then reads the review again and shows what it answers", async () => { + const reviewPurge = vi + .fn() + .mockResolvedValueOnce({ + kind: "review", + review: { + piRead: true, + unserved: [ + { id: "gap-1", provider: "opencode" }, + { id: "gap-2", provider: "opencode-go" }, + ], + }, + }) + .mockResolvedValue({ + kind: "review", + review: { + piRead: true, + unserved: [{ id: "gap-2", provider: "opencode-go" }], + }, + }); + let finish: (value: unknown) => void = () => {}; + const removeUnserved = vi.fn( + () => + new Promise((resolve) => { + finish = resolve; + }) + ); + const { act, button, cleanup, host, settle } = await mount({ + purgeDeprecated, + removeUnserved, + reviewPurge, + }); + try { + expect(host.textContent).toContain( + "opencode: gap-1 · opencode-go: gap-2" + ); + expect(host.textContent).toContain(en.unservedTitle); + const remove = button(en.unservedAction); + expect(remove, "the removal button is rendered").toBeDefined(); + act(() => { + remove?.click(); + }); + await settle(); + expect(removeUnserved).toHaveBeenCalledTimes(1); + expect(button(en.unservedBusy)).toBeDefined(); + act(() => { + finish({ + kind: "purged", + result: { + catalogRead: true, + removed: [{ id: "gap-1", provider: "opencode" }], + }, + }); + }); + await settle(); + expect(host.textContent).toContain(`1 ${en.unservedRemoved}`); + expect(reviewPurge).toHaveBeenCalledTimes(2); + // The second answer is what the card shows: gap-1 is gone. + expect(host.textContent).toContain("opencode-go: gap-2"); + expect(host.textContent).not.toContain("gap-1"); + } finally { + cleanup(); + } + }); + + it("reads the review again after a purge, and not again for a parent render with a fresh closure", async () => { + const reviewPurge = vi.fn(async () => listing("gap-1")); + const { act, button, cleanup, render, settle } = await mount({ + purgeDeprecated, + removeUnserved: vi.fn(), + reviewPurge, + }); + try { + expect(reviewPurge).toHaveBeenCalledTimes(1); + // The page builds new closures on every `inject()`: a re-render with + // one is not a reason to review again. + const fresh = vi.fn(async () => listing("gap-1")); + render({ purgeDeprecated, removeUnserved: vi.fn(), reviewPurge: fresh }); + await settle(); + expect(reviewPurge).toHaveBeenCalledTimes(1); + expect(fresh).not.toHaveBeenCalled(); + // A purge that settles reads it again, through the latest closure. + act(() => { + button(en.purgeAction)?.click(); + }); + await settle(); + expect(fresh).toHaveBeenCalledTimes(1); + expect(reviewPurge).toHaveBeenCalledTimes(1); + } finally { + cleanup(); + } + }); + + it("drops a review answer that arrives after a newer round's", async () => { + let late: (value: unknown) => void = () => {}; + const reviewPurge = vi + .fn() + .mockImplementationOnce( + () => + new Promise((resolve) => { + late = resolve; + }) + ) + .mockResolvedValue(listing("gap-new")); + const { act, button, cleanup, host, settle } = await mount({ + purgeDeprecated, + removeUnserved: vi.fn(), + reviewPurge, + }); + try { + act(() => { + button(en.purgeAction)?.click(); + }); + await settle(); + expect(reviewPurge).toHaveBeenCalledTimes(2); + expect(host.textContent).toContain("opencode: gap-new"); + act(() => { + late(listing("gap-old")); + }); + await settle(); + expect(host.textContent).toContain("opencode: gap-new"); + expect(host.textContent).not.toContain("gap-old"); + } finally { + cleanup(); + } + }); + + it("says, in the warn colour, when the review could not read pi's catalog", async () => { + const { button, cleanup, host } = await mount({ + purgeDeprecated, + removeUnserved: vi.fn(), + reviewPurge: async () => ({ + kind: "review", + review: { piRead: false, unserved: [] }, + }), + }); + try { + expect(button(en.unservedAction)).toBeUndefined(); + const line = [...host.querySelectorAll("div")].find( + (d) => d.textContent === en.unservedPiUnreadReview + ); + expect(line, "the pi-unread caption").toBeDefined(); + expect(line?.style.color).toBe("var(--dsw-alias-state-warn-label)"); + } finally { + cleanup(); + } + }); + + it("tells a removal that could not read pi apart from a review that could not, each line once", async () => { + // A review lists an id, the removal's own read of pi fails, and the + // review read again cannot read pi either: the outcome and the review's + // state are two different sentences, and each is said once. + const reviewPurge = vi + .fn() + .mockResolvedValueOnce(listing("gap-1")) + .mockResolvedValue({ + kind: "review", + review: { piRead: false, unserved: [] }, + }); + const removeUnserved = vi.fn(async () => ({ + kind: "purged", + result: { catalogRead: false, removed: [] }, + })); + const { act, button, cleanup, host, settle } = await mount({ + purgeDeprecated, + removeUnserved, + reviewPurge, + }); + try { + expect(host.textContent).not.toContain(en.unservedPiUnreadReview); + act(() => { + button(en.unservedAction)?.click(); + }); + await settle(); + expect(removeUnserved).toHaveBeenCalledTimes(1); + expect(reviewPurge).toHaveBeenCalledTimes(2); + const lines = (text: string) => + [...host.querySelectorAll("div")].filter((d) => d.textContent === text); + expect(lines(en.unservedPiUnread)).toHaveLength(1); + expect(lines(en.unservedPiUnreadReview)).toHaveLength(1); + expect(en.unservedPiUnreadReview).not.toBe(en.unservedPiUnread); + } finally { + cleanup(); + } + }); + + it("renders no removal when the review lists nothing, and the catalog's error in the warn colour", async () => { + const { button, cleanup, host } = await mount({ + purgeDeprecated, + removeUnserved: vi.fn(), + reviewPurge: async () => ({ + kind: "review", + review: { catalogError: "offline", piRead: true, unserved: [] }, + }), + }); + try { + expect(button(en.unservedAction)).toBeUndefined(); + const line = [...host.querySelectorAll("div")].find((d) => + (d.textContent ?? "").startsWith(en.catalogLastError) + ); + expect(line?.textContent).toBe(`${en.catalogLastError}: offline`); + expect(line?.style.color).toBe("var(--dsw-alias-state-warn-label)"); + } finally { + cleanup(); + } + }); + + it("renders the row as before with no review, and nothing extra for an outcome that is not a review", async () => { + for (const extra of [ + { purgeDeprecated }, + { purgeDeprecated, reviewPurge: async () => ({ kind: "unavailable" }) }, + ]) { + const { cleanup, host } = await mount(extra); + try { + expect(host.textContent).toContain(en.purgeAction); + expect(host.textContent).not.toContain(en.unservedTitle); + expect(host.textContent).not.toContain(en.catalogLastError); + } finally { + cleanup(); + } + } + }); +}); diff --git a/test/settings-page.test.tsx b/test/settings-page.test.tsx index 089269d..ab5e277 100644 --- a/test/settings-page.test.tsx +++ b/test/settings-page.test.tsx @@ -111,7 +111,7 @@ describe("settings-page: apply & slots", () => { expect(dockRegistrations).toHaveLength(0); }); - it("unregisters every alias when the plugin unloads", () => { + it("unregisters every alias when the plugin unloads, and joins the purge row's callbacks to their methods", async () => { // The registrations above are only half the contract: a reload (or a profile // edit that restarts the entry) tears the bundle down, and the card must go // with it. Nothing asserted the disposers, so a card that outlived its @@ -187,6 +187,46 @@ describe("settings-page: apply & slots", () => { expect(typeof mount?.[action]).toBe("function"); } + // The purge row's three callbacks, each joined to its own host method. + // The card reads the review on mount, so a review wired to the removal + // would rewrite the profile whenever Settings opens: each callback must + // reach exactly its method, with no argument. The remote is set after + // apply, as the host's mount lands after it, and read per call. + const calls: [string, unknown[]][] = []; + const answer = (method: string, value: unknown) => + vi.fn(async (...args: unknown[]) => { + calls.push([method, args]); + return { ok: true, value }; + }); + (ctx as Record).remote = { + opencodeModelPurge: { + purge: answer("purge", { catalogRead: true, removed: [] }), + removeUnserved: answer("removeUnserved", { + catalogRead: true, + removed: [], + }), + review: answer("review", { piRead: true, unserved: [] }), + }, + }; + const call = async (name: string): Promise<{ kind: string }> => { + const callback = mount?.[name]; + if (typeof callback !== "function") { + throw new TypeError(`the card's mount has no ${name}`); + } + return (callback as () => Promise<{ kind: string }>)(); + }; + for (const [callback, method, kind] of [ + ["reviewPurge", "review", "review"], + ["removeUnserved", "removeUnserved", "purged"], + ["purgeDeprecated", "purge", "purged"], + ] as const) { + calls.length = 0; + // oxlint-disable-next-line no-await-in-loop -- one callback at a time, so each call list is its own. + const outcome = await call(callback); + expect(outcome.kind, callback).toBe(kind); + expect(calls, callback).toEqual([[method, []]]); + } + teardown?.(); expect(disposed).toEqual([PKG, SCOPED_PKG, LEGACY_NS]); diff --git a/test/settings-purge.test.ts b/test/settings-purge.test.ts index 3dc95fc..c34c6cc 100644 --- a/test/settings-purge.test.ts +++ b/test/settings-purge.test.ts @@ -5,7 +5,11 @@ */ import { describe, expect, it, vi } from "vitest"; -import { purgeDeprecatedModels } from "../src/settings-purge.ts"; +import { + purgeDeprecatedModels, + removeUnservedModels, + reviewPurge, +} from "../src/settings-purge.ts"; const scopeWith = (purge: unknown): unknown => ({ remote: { opencodeModelPurge: { purge } }, @@ -265,3 +269,108 @@ describe("purgeDeprecatedModels: the one unwrap (P9), on shapes the host does no } }); }); + +describe("reviewPurge and removeUnservedModels: the one unwrap", () => { + const scope = (methods: Record): unknown => ({ + remote: { opencodeModelPurge: methods }, + }); + + it("reviewPurge answers the host's review, parsed", async () => { + const review = vi.fn(async (..._args: unknown[]) => ({ + ok: true, + value: { piRead: true, unserved: [] }, + })); + await expect(reviewPurge(scope({ review }))).resolves.toEqual({ + kind: "review", + review: { piRead: true, unserved: [] }, + }); + expect(review).toHaveBeenCalledWith(); + }); + + it("reviewPurge says nothing in the console when the service is absent", async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + await expect(reviewPurge({ remote: {} })).resolves.toEqual({ + kind: "unavailable", + }); + expect(warn).not.toHaveBeenCalled(); + } finally { + warn.mockRestore(); + } + }); + + it("reviewPurge names a refusal, a rejection and a value that is not a review", async () => { + await expect( + reviewPurge( + scope({ review: async () => ({ error: { message: "m" }, ok: false }) }) + ) + ).resolves.toEqual({ kind: "failed", message: "m" }); + await expect( + reviewPurge(scope({ review: () => Promise.reject(new Error("gone")) })) + ).resolves.toEqual({ kind: "failed", message: "gone" }); + await expect( + reviewPurge(scope({ review: async () => ({ ok: true, value: {} }) })) + ).resolves.toEqual({ + kind: "failed", + message: "the host answered something that is not a purge review", + }); + await expect( + // oxlint-disable-next-line prefer-promise-reject-errors -- the case is a rejection that is not an Error. + reviewPurge(scope({ review: () => Promise.reject("down") })) + ).resolves.toEqual({ kind: "failed", message: "down" }); + }); + + it("removeUnservedModels answers a purge result", async () => { + const result = { + catalogRead: true, + removed: [{ id: "gap", provider: "opencode" }], + }; + const removeUnserved = vi.fn(async (..._args: unknown[]) => ({ + ok: true, + value: result, + })); + await expect( + removeUnservedModels(scope({ removeUnserved })) + ).resolves.toEqual({ kind: "purged", result }); + expect(removeUnserved).toHaveBeenCalledWith(); + }); + + it("removeUnservedModels names an absent service, a refusal and a value that is not a purge result, in the purge's words", async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + await expect(removeUnservedModels({ remote: {} })).resolves.toEqual({ + kind: "unavailable", + }); + // The purge row's own call names a missing service; this one does not. + expect(warn).not.toHaveBeenCalled(); + } finally { + warn.mockRestore(); + } + await expect( + removeUnservedModels( + scope({ + removeUnserved: async () => ({ + error: { message: "no config editor" }, + ok: false, + }), + }) + ) + ).resolves.toEqual({ kind: "failed", message: "no config editor" }); + await expect( + removeUnservedModels( + scope({ removeUnserved: async () => ({ error: {}, ok: false }) }) + ) + ).resolves.toEqual({ + kind: "failed", + message: "the host refused the purge", + }); + await expect( + removeUnservedModels( + scope({ removeUnserved: async () => ({ ok: true, value: {} }) }) + ) + ).resolves.toEqual({ + kind: "failed", + message: "the host answered something that is not a purge result", + }); + }); +}); diff --git a/test/settings-snapshot.test.ts b/test/settings-snapshot.test.ts index ac01378..bff90e4 100644 --- a/test/settings-snapshot.test.ts +++ b/test/settings-snapshot.test.ts @@ -264,6 +264,7 @@ const CHOICE_KEYS = { /** Every copy key that stays, in both languages. */ const LIVE_KEYS = [ + "catalogLastError", "description", "endpoint", "endpointAuto", @@ -333,6 +334,14 @@ const LIVE_KEYS = [ "storeInspectUnavailable", "storeInspectValid", "unavailable", + "unservedAction", + "unservedBusy", + "unservedHint", + "unservedNothing", + "unservedPiUnread", + "unservedPiUnreadReview", + "unservedRemoved", + "unservedTitle", "usageAuthRejected", "usageConsole", "usageEnabled", @@ -733,7 +742,9 @@ describe("the settings, as the plugin derives them", () => { }); it("the copy keys: the full list, in both languages", () => { - expect(LIVE_KEYS).toHaveLength(104); + // 104 through P10a; P10b adds the review's nine (`catalogLastError` and + // the eight `unserved*` keys). + expect(LIVE_KEYS).toHaveLength(113); const expected = [...LIVE_KEYS, "appliesOnReapply"].toSorted(); expect(Object.keys(en).toSorted()).toStrictEqual(expected); expect(Object.keys(zh).toSorted()).toStrictEqual(expected); diff --git a/test/support/catalogs.ts b/test/support/catalogs.ts index 0d109cc..2749d07 100644 --- a/test/support/catalogs.ts +++ b/test/support/catalogs.ts @@ -24,12 +24,16 @@ * @module test/support/catalogs */ +import type { ShimData } from "../../scripts/catalog-shim.ts"; import { type CatalogModelSpec, + OPENCODE_FAMILY_API, OPENCODE_GO_CATALOG, + OPENCODE_PLANE_API, OPENCODE_ZEN_CATALOG, protocolForSdk, refreshCatalog, + shippedDeprecatedIds, } from "./src.ts"; /** The two plane routes the shims describe. */ @@ -255,9 +259,10 @@ export const GO_FREE_PROBE = "go-probe"; * * A request-path test needs the world installed where the shipped lookup reads * it, so this goes through `refreshCatalog` (the stubbed fetch never touches the - * network). `refreshCatalog` merges into the live maps, and - * `test/support/reset-process-state.ts` restores the shim after every test, so - * a case seeds its own world. + * network). The refresh REPLACES each plane it carries rows for, so the two + * probes are the whole live catalog of both planes until + * `test/support/reset-process-state.ts` restores the shim after the test; a + * case seeds its own world. * * @returns once the live maps carry both probes. */ @@ -274,3 +279,101 @@ export const seedDivergentCatalog = async (): Promise => { }); await refreshCatalog(async () => Response.json(body), true); }; + +/** + * What the shipped shim exports, in the shape the generator's staleness rule + * compares (`scripts/catalog-shim.ts`'s `ShimData`), its retired ids included. + * + * Read through the door's names, so the retired ids come through the same + * tolerant read the runtime seeds from: an empty list per plane until the + * generated file carries them. + * + * @returns the five values. + */ +export const shippedShimData = (): ShimData => ({ + deprecated: shippedDeprecatedIds(), + familyApi: OPENCODE_FAMILY_API, + go: OPENCODE_GO_CATALOG, + planeApi: OPENCODE_PLANE_API, + zen: OPENCODE_ZEN_CATALOG, +}); + +/** + * A models.dev payload that reproduces `data`, changed as a case says. + * + * Every row carries the fields the parser reads (its limits, cost, modalities + * and reasoning) and its family's endpoint as its own `provider.api`; each + * plane's endpoint is the provider's `api`; and every id in + * `data.deprecated[plane]` is a `status: "deprecated"` row. A family no live + * row names is carried by one of those retired rows, so the family map is the + * shipped one and no retired id is added that the data does not hold. The + * payload reproduces the data only when every such family has a retired id to + * carry it, which a generated shim always has (the generator reads families + * off retired rows too); data that has a family left over throws rather than + * invent a row. The inverse of `parseModelsDevCatalog` then `shimData`, which + * the generator's "current" cases hold. + * + * @param data - the shim to reproduce (`shippedShimData()` for the shipped one). + * @param changes - ids moved to `status: "deprecated"`, and rows added, per plane. + * @returns the payload the parser reads. + */ +export const registryOf = ( + data: ShimData, + changes: { + retire?: Partial>; + add?: { go?: readonly SpecInput[]; zen?: readonly SpecInput[] }; + } = {} +): Record => { + const provider = (plane: "go" | "zen"): Record => { + const families = data.familyApi[plane]; + const retire = new Set(changes.retire?.[plane]); + const live = data[plane].filter((row) => !retire.has(row.id)); + const models: Record = {}; + for (const row of live) { + const npm = row.provider_npm ?? ""; + const api = families[npm]; + models[row.id] = { + ...(row.cost === undefined ? {} : { cost: row.cost }), + id: row.id, + limit: { context: row.context_window, output: row.max_output_tokens }, + modalities: { input: row.input_modalities }, + name: row.name, + provider: { + ...(api === undefined ? {} : { api }), + ...(npm === "" ? {} : { npm }), + }, + ...(row.reasoning === undefined ? {} : { reasoning: row.reasoning }), + ...(row.reasoning_options === undefined + ? {} + : { reasoning_options: row.reasoning_options }), + }; + } + const retired = [...new Set([...data.deprecated[plane], ...retire])]; + const named = new Set(live.map((row) => row.provider_npm ?? "")); + const orphans = Object.entries(families).filter(([npm]) => !named.has(npm)); + for (const id of retired) { + const [family] = orphans.splice(0, 1); + models[id] = { + ...(family === undefined + ? {} + : { + provider: { + api: family[1], + ...(family[0] === "" ? {} : { npm: family[0] }), + }, + }), + status: "deprecated", + }; + } + if (orphans.length > 0) { + throw new Error( + `registryOf: ${plane} family ${orphans.map(([npm]) => JSON.stringify(npm)).join(", ")} has no live or retired row to carry it` + ); + } + for (const row of changes.add?.[plane] ?? []) { + models[row.id] = modelEntry(row); + } + return { api: data.planeApi[plane], models }; + }; + return { "opencode-go": provider("go"), opencode: provider("zen") }; +}; diff --git a/test/support/src.ts b/test/support/src.ts index 4da7a02..883955b 100644 --- a/test/support/src.ts +++ b/test/support/src.ts @@ -81,6 +81,7 @@ export { REMOTE_CONTRACTS } from "../../src/contracts/all.ts"; // contracts/purge.ts export { parsePurgeResult, + parsePurgeReview, PURGE_NAMESPACE, purgeRemote, } from "../../src/contracts/purge.ts"; @@ -121,6 +122,7 @@ export type { // cordis-context.ts export { + loadHostLibraries, loadHostModules, loaderOfContext, PI_AI_RUNTIME, @@ -253,7 +255,9 @@ export { apply } from "../../src/lifecycle.ts"; // models-catalog.ts export { catalogGeneration, + catalogLastError, catalogListenerCount, + deprecatedIdsOf, enrichModelsResponse, findModelSpec, findModelSpecOn, @@ -269,9 +273,11 @@ export { refreshCatalog, resetCatalogState, sanitizeModalities, + shippedDeprecatedIds, specFor, specOn, } from "../../src/models-catalog.ts"; +export type { CatalogRefresh } from "../../src/models-catalog.ts"; // opencode-paths.ts export { @@ -293,6 +299,7 @@ export { // purge-service.ts export { ModelPurgeService, + purgeEntryConfig, stripRetiredReferences, } from "../../src/purge-service.ts"; @@ -340,7 +347,12 @@ export { SettingsBooleanField } from "../../src/settings-boolean-field.tsx"; export type { BooleanFieldProps } from "../../src/settings-boolean-field.tsx"; // settings-card.tsx -export { OpencodeCard, purgeLine } from "../../src/settings-card.tsx"; +export { + OpencodeCard, + purgeLine, + reviewLines, + unservedLine, +} from "../../src/settings-card.tsx"; // settings-choice-field.tsx export { SettingsChoiceField } from "../../src/settings-choice-field.tsx"; @@ -367,7 +379,11 @@ export { } from "../../src/settings-page.tsx"; // settings-purge.ts -export { purgeDeprecatedModels } from "../../src/settings-purge.ts"; +export { + purgeDeprecatedModels, + removeUnservedModels, + reviewPurge, +} from "../../src/settings-purge.ts"; // settings-remote.ts export { @@ -545,6 +561,7 @@ export { hasPlaneEntries, planeEntriesOf, planeProfileFor, + piUnservedIds, withoutPlaneProviders, } from "../../src/utils/plane-profile.ts"; export type { PlaneProfileInput } from "../../src/utils/plane-profile.ts";