pi-sap-aicore 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-21
+
+### Added
+
+- Registered complete Pi 0.81 `Provider` objects for both orchestration and
+  foundation routes, including native authentication, synchronous model views,
+  provider refresh, and both streaming methods.
+- Added native API-key login for SAP service-key JSON. Pi stores and resolves the
+  credential verbatim, preserving literal `$` characters in `clientsecret`.
+- Integrated the layered SAP catalog with Pi's provider refresh lifecycle. `/model`
+  and `pi update --models` can refresh it automatically, while `/sap-models update`
+  forces an immediate refresh without replacing Provider objects.
+- Added offline regression coverage for native Provider shape, API-key and legacy
+  auth, shared foundation credentials, refresh throttling, abort/failure retention,
+  concurrent refresh deduplication, and stale-cache protection.
+
+### Changed
+
+- Existing fake-OAuth credentials remain supported without re-login, but new users
+  should authenticate through `/login` → **Sign in with an API key**.
+- Raised the minimum supported Pi version to 0.81.0 and Node.js to 22.19.0.
+  Users remaining on Pi 0.80.x should pin `pi-sap-aicore@0.3.8`.
+- Older per-machine model caches no longer override a newer bundled snapshot after
+  an extension upgrade.
+
+### Fixed
+
+- Declared `@sap-ai-sdk/core` as a direct dependency because the Bedrock and Vertex
+  adapters import it directly; strict and pnpm installations no longer depend on
+  transitive hoisting.
+
+## [0.3.8] - 2026-07-18
+
+### Fixed
+
+- SAP AI Core no longer appears configured in `/login` on a fresh install.
+  The orchestration provider now declares its `AICORE_SERVICE_KEY` environment
+  fallback explicitly instead of using an always-configured placeholder; stored
+  subscription credentials continue to use the existing OAuth-backed login.
+
 ## [0.3.7] - 2026-07-16
 
 ### Fixed
@@ -243,7 +283,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `reasoning_effort` for OpenAI).
 - MIT license and npm packaging.
 
-[Unreleased]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.3.7...HEAD
+[Unreleased]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.3.8...v0.4.0
+[0.3.8]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.3.7...v0.3.8
 [0.3.7]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.3.6...v0.3.7
 [0.3.6]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.3.5...v0.3.6
 [0.3.5]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.3.4...v0.3.5

package/README.md

@@ -9,13 +9,23 @@ and share one login, so you pick the route per model. See
 
 ## Prerequisites
 
-- pi **0.78.0 or newer** installed (`npm install -g @earendil-works/pi-coding-agent`)
+- pi **0.81.0 or newer** installed (`npm install -g @earendil-works/pi-coding-agent`)
+- Node.js **22.19.0 or newer**
 - An SAP BTP account with AI Core entitlement and an **orchestration deployment**
 - *(optional, for the foundation provider)* one or more **foundation-models
   deployments** — one per model you want to route directly (`azure-openai` for
   GPT/OpenAI models, `aws-bedrock` for Anthropic/Claude models)
 - The service key JSON for your AI Core service binding
 
+> [!IMPORTANT]
+> `pi-sap-aicore` **0.4.0 and newer require pi 0.81.0 or newer** because they
+> use pi's complete native Provider API. If you must remain on pi 0.80.x, pin
+> the previous compatible extension release until you can upgrade:
+>
+> ```bash
+> pi install npm:pi-sap-aicore@0.3.8
+> ```
+
 ## Credentials
 
 The extension looks for the SAP BTP service-key JSON in this order:
@@ -41,28 +51,28 @@ From inside pi:
 ```
 
 Then:
-1. Pick **Use a subscription**.
+
+1. Pick **Sign in with an API key**.
 2. Pick **SAP AI Core**.
-3. At the prompt, paste your BTP service-key JSON as a single line and hit enter.
+3. Paste your BTP service-key JSON as a single line and hit enter.
    It's validated immediately — if anything is missing or malformed, you'll get a
    specific error pointing at the field, so you can re-run `/login` and fix it.
 
-Pi stores the JSON in `~/.pi/agent/auth.json` for future sessions.
+Pi 0.81 stores the JSON as a native provider credential in
+`~/.pi/agent/auth.json`. The value is passed to the provider verbatim, so literal
+`$` characters in `clientsecret` are preserved.
 
 To get the JSON: BTP cockpit → your AI Core service instance → Service Keys
 → View. Copy the entire JSON object.
 
-> **Why "Use a subscription" and not "Use an API key"?** SAP service keys contain
-> a `$` in their `clientsecret`. Since pi 0.77, keys stored via "Use an API key"
-> are run through a `$`-interpolating template resolver that mangles them. The
-> extension registers credentials through pi's `oauth` mechanism instead, which
-> stores and returns the key verbatim. It's not real OAuth — it's just the path
-> that keeps your key intact. (See [pi issue #5095](https://github.com/earendil-works/pi/issues/5095).)
-
-> **Upgrading from an older install?** If you previously logged in via
-> "Use an API key" (stored as `{"type":"api_key"}` in `auth.json`), re-run
-> `/login` **once** via **Use a subscription** to convert the stored credential.
-> A single re-login is all that's needed.
+> **Upgrading from 0.3.x?** Existing credentials created through
+> **Use a subscription → SAP AI Core** continue to work without re-login. The
+> Pi 0.81 provider retains that legacy credential handler solely for migration;
+> new logins should use the native API-key flow above. The foundation provider
+> still borrows the primary `sap-aicore` credential and does not add a second
+> subscription entry. Pi may list **SAP AI Core (Foundation)** in the API-key
+> provider picker because every complete Provider declares auth; choose the
+> primary **SAP AI Core** entry when you want one credential shared by both.
 
 ### Alternative: `AICORE_SERVICE_KEY` env var
 
@@ -102,6 +112,7 @@ pi -e ./index.ts --list-models
 
 You'll see the orchestration models under `sap-aicore/` (Claude, GPT-5*, Gemini),
 plus any direct **foundation** models under `sap-aicore-foundation/`:
+
 - `sap-aicore/anthropic--claude-4.7-opus` — Claude Opus 4.7 (orchestration)
 - `sap-aicore/gpt-5.5` — GPT-5.5 via orchestration
 - `sap-aicore-foundation/gpt-5.5` — GPT-5.5 via its direct Azure OpenAI foundation deployment
@@ -129,7 +140,7 @@ updates.
 The extension registers **two providers**, both backed by the same service key:
 
 | | `sap-aicore` (orchestration) | `sap-aicore-foundation` (direct) |
-|---|---|---|
+| --- | --- | --- |
 | SAP deployment | one orchestration deployment fronts **every** model | one foundation deployment **per model** |
 | Models | Claude, GPT-5*, Gemini | GPT/OpenAI (`azure-openai`), Anthropic/Claude (`aws-bedrock`), and Gemini (`gcp-vertexai`) |
 | Tool use | yes | yes — tools are translated to OpenAI, Bedrock Converse, or Vertex/Gemini function declarations by executable |
@@ -187,21 +198,28 @@ The model list is composed of three sources, merged at startup:
 1. **`src/models-snapshot.json`** — packaged fallback catalog, auto-generated
    from [models.dev](https://models.dev)'s SAP AI Core catalog. Maintainers
    refresh it with:
+
    ```bash
    npm run update-models
    ```
+
    This re-fetches the live catalog, applies our family-specific filters
    (currently anthropic claude-4.x, gpt-5*, gemini-2.5*), and writes the
    snapshot to disk. Commit the result.
 
 2. **`~/.pi/agent/pi-sap-aicore/models-cache.json`** — per-machine public
-   catalog cache. Users refresh it inside pi with:
+   catalog cache. Pi 0.81 refreshes authenticated providers in the background
+   when `/model` opens and through `pi update --models`; checks are throttled for
+   four hours. Force an immediate refresh inside pi with:
+
    ```text
    /sap-models update
    ```
+
    This does not edit the installed npm package and is safe across extension
-   updates. The command re-registers the SAP providers for the current session;
-   restart pi or `/reload` if another session should pick it up.
+   updates. The existing Provider objects publish the refreshed model list
+   immediately, without re-registration or `/reload`. A cache older than the
+   bundled snapshot is ignored after extension upgrades.
 
 3. **`~/.pi/agent/pi-sap-aicore/models.json`** — per-machine tenant overlay.
    Use it for models in your tenant that are not in the public catalog yet,
@@ -250,8 +268,8 @@ tenant reports.
 Run these inside pi after installing/loading the extension:
 
 | Command | What it does |
-|---|---|
-| `/sap-models update` | Fetches the latest public SAP AI Core model metadata from models.dev, writes `~/.pi/agent/pi-sap-aicore/models-cache.json`, and re-registers the SAP providers for the current session. |
+| --- | --- |
+| `/sap-models update` | Forces the latest public SAP AI Core model metadata from models.dev into `~/.pi/agent/pi-sap-aicore/models-cache.json` and updates both live Provider views. |
 | `/sap-models discover` | Uses your configured SAP service key to query the tenant's `foundation-models` scenario, then reports models that are missing from the local catalog and catalog entries absent from the tenant. Honors `AICORE_RESOURCE_GROUP` / service-key `resourceGroup`. |
 | `/sap-models list` | Shows how many orchestration models and foundation-enabled models are currently loaded after snapshot/cache/overlay merging. |
 | `/sap-models paths` | Prints the cache and overlay file paths for this machine. |
@@ -275,7 +293,7 @@ to `exclude`.
 `~/.pi/agent/pi-sap-aicore/models.json` supports these top-level fields:
 
 | Field | Type | Purpose |
-|---|---|---|
+| --- | --- | --- |
 | `models` | `SapModel[]` | Adds tenant-only/pre-release models or replaces catalog models with the same `id`. |
 | `overrides` | object keyed by model id | Partially overrides an existing model. Nested `limit`, `cost`, `modalities`, and `thinkingLevelMap` fields are merged. Unknown ids are ignored. |
 | `exclude` | `string[]` | Removes model ids after snapshot/cache/overlay merging. Useful for public catalog entries your SAP tenant does not deploy. |
@@ -343,6 +361,7 @@ into the visible answer text, and the tokens are billed via
 "thinking" panel will stay empty for SAP-routed models — there's no
 client-side fix. If SAP exposes a server-side flag for this in the
 future, our `pickReasoning` probe is wired and ready in `stream.ts`.
+
 - **OpenAI models** (`gpt-*`) use `reasoning_effort: "minimal" | "low"
   | "medium" | "high"`. `xhigh` is omitted — OpenAI has no equivalent
   tier; pi will skip it when cycling.
@@ -370,15 +389,19 @@ To override budgets per model, edit `thinkingLevelMap` on the relevant entry in
 Resolved in this order:
 
 1. **`AICORE_RESOURCE_GROUP` env var** — per-shell override. Example:
+
    ```bash
    export AICORE_RESOURCE_GROUP=my-team-rg
    ```
+
 2. **`resourceGroup` field on the service-key JSON** — convenient for teams
    who manage multiple groups and want to bake the default into the key.
    Non-standard, so add it yourself before pasting into pi:
+
    ```json
    { "clientid": "...", "clientsecret": "...", "resourceGroup": "my-team-rg", ... }
    ```
+
 3. **SAP's server-side default** (`default`) — if neither of the above is set.
 
 The value is passed via SAP's `OrchestrationClient(..., {resourceGroup})`
@@ -429,10 +452,12 @@ build step — pi loads the `.ts` sources directly via jiti — so a release is
 1. Update `CHANGELOG.md`: move items from `[Unreleased]` into a new version
    heading.
 2. Bump the version (this commits `package.json` and creates a `vX.Y.Z` tag):
+
    ```bash
    npm version patch   # or minor / major
    git push --follow-tags
    ```
+
 3. The [`Publish`](.github/workflows/publish.yml) workflow fires on the `v*` tag,
    asserts the tag matches `package.json`, typechecks, publishes to npm, and
    creates/updates the matching GitHub Release from that version's
@@ -468,20 +493,23 @@ npmjs.com:
 ├── .github/workflows/
 │   ├── ci.yml                # typecheck gate on push to main + PRs
 │   └── publish.yml           # tag-driven npm publish via OIDC trusted publishing
-├── index.ts                  # ExtensionAPI factory + registerProvider calls (both providers)
+├── index.ts                  # ExtensionAPI factory + complete Provider registration
 ├── scripts/
 │   ├── update-models.mjs                    # maintainer script: fetches models.dev, writes models-snapshot.json
 │   ├── list-sap-models.mjs                  # lists models your tenant actually deploys (diff vs snapshot)
 │   ├── diagnose-streaming.mjs               # probes orchestration streaming support per model
+│   ├── test-native-providers.mjs            # offline Provider/auth compatibility checks
+│   ├── test-model-refresh.mjs               # offline refresh/cache/failure checks
 │   └── validate-foundation-executables.mjs  # live text/tool/image smoke tests for direct foundation executables
 └── src/
-    ├── auth.ts                  # service-key validation + pi oauth registration
+    ├── auth.ts                  # native API-key auth + legacy credential compatibility
     ├── model-catalog.ts         # loads snapshot/cache/overlay and adapts models.dev metadata
-    ├── models-config.ts         # exposes merged MODELS and FOUNDATION_MODELS
+    ├── model-catalog-controller.ts # shared synchronous state + refresh lifecycle
     ├── models-snapshot.json     # auto-generated from models.dev (committed)
+    ├── providers.ts             # complete Pi 0.81 Provider objects
     ├── sap-model-commands.ts    # /sap-models update/discover/list/paths
-    ├── to-pi-model.ts           # SapModel → pi's ProviderModelConfig mapper
-    ├── stream.ts                # orchestration streamSimple adapter + shared helpers (auth, usage, errors)
+    ├── to-pi-model.ts           # SapModel → pi-ai Model mapper
+    ├── stream.ts                # orchestration stream adapter + shared usage/error helpers
     ├── translate.ts             # pi Context ↔ orchestration message shape
     ├── foundation-executables.ts         # model id → SAP foundation executable mapping
     ├── foundation-deployment.ts          # shared foundation deployment resolution helpers

package/index.ts

@@ -1,83 +1,21 @@
-import type { Api } from "@earendil-works/pi-ai";
+import type { Provider } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { sapAiCoreOAuth } from "./src/auth.ts";
-import { loadModelCatalog } from "./src/model-catalog.ts";
+import { createSapModelCatalogController } from "./src/model-catalog-controller.ts";
+import { createSapProviders } from "./src/providers.ts";
 import { registerSapModelCommands } from "./src/sap-model-commands.ts";
-import { streamSapAiCore } from "./src/stream.ts";
-import { streamSapFoundation } from "./src/stream-foundation.ts";
-import { toPiModel } from "./src/to-pi-model.ts";
-
-const PROVIDER_NAME = "sap-aicore";
-const PROVIDER_API = "sap-aicore-orchestration" as Api;
-
-// Second provider: direct foundation (Azure OpenAI) deployments, registered
-// alongside orchestration so both routes are independently selectable
-// (e.g. `sap-aicore/gpt-5.5` vs `sap-aicore-foundation/gpt-5.5`).
-const FOUNDATION_PROVIDER_NAME = "sap-aicore-foundation";
-const FOUNDATION_PROVIDER_API = "sap-aicore-foundation" as Api;
-
-// pi requires a non-empty `apiKey` for any custom provider that defines models
-// (model-registry `validateConfig`), even when credentials come from `oauth`.
-// This value is never used: the real key is supplied by `sapAiCoreOAuth`
-// (after `/login`) or by AICORE_SERVICE_KEY (both handled in stream.ts). It is a
-// plain lowercase literal so pi's config-value resolver returns it as-is — no
-// `$` interpolation, no shell exec, and not mistaken for a legacy env-var name.
-const PLACEHOLDER_API_KEY = "managed-by-extension-oauth";
 
 export default function (pi: ExtensionAPI) {
-	const registerProviders = () => {
-		const catalog = loadModelCatalog();
-		const models = catalog.models;
-		const foundationModels = models.filter((m) =>
-			catalog.foundationModelIds.has(m.id),
-		);
-
-		pi.registerProvider(PROVIDER_NAME, {
-			name: "SAP AI Core",
-			baseUrl: "https://sap-aicore-handled-by-sdk.invalid",
-			apiKey: PLACEHOLDER_API_KEY,
-			api: PROVIDER_API,
-			// Credentials flow through pi's `oauth` path — its escape hatch from the
-			// $-interpolating config-value resolver that corrupts service keys
-			// containing `$` (SAP keys have one in `clientsecret`). `/login → Use a
-			// subscription → SAP AI Core` captures the service-key JSON; `getApiKey`
-			// returns it verbatim as `options.apiKey` to `streamSimple`.
-			oauth: sapAiCoreOAuth,
-			// Resource-group selection lives in stream.ts (passed to
-			// OrchestrationClient's deploymentConfig); SAP's typings reject
-			// it as a header (`'AI-Resource-Group'?: never`). A `headers`
-			// entry here would also be a no-op anyway — pi only forwards
-			// `headers` when it makes the HTTP request itself, but we use
-			// `streamSimple` and the SAP SDK handles transport.
-			models: models.map((m) => toPiModel(m, PROVIDER_API)),
-			// Synchronous, as pi's provider contract requires. The SAP SDK is still
-			// deferred to first use — `stream.ts` only `import type`s it at module
-			// load and dynamically imports the OrchestrationClient inside the stream
-			// producer, surfacing a missing-dependency error through the stream.
-			streamSimple: streamSapAiCore,
-		});
-
-		// Foundation provider — shares the exact same credential via
-		// `ensureServiceKey`'s auth-store fallback instead of registering its own
-		// OAuth provider. Registering `oauth: sapAiCoreOAuth` here would make `/login`
-		// show a second, confusing "SAP AI Core" subscription entry because pi keys
-		// OAuth providers by provider id (`sap-aicore-foundation`), not by OAuth name.
-		// Models appear under `sap-aicore-foundation/…`; streaming runs natively here
-		// (no orchestration streaming-unsupported fallback). The foundation SDK is
-		// dynamically imported inside `streamSapFoundation`, same deferral as above.
-		pi.registerProvider(FOUNDATION_PROVIDER_NAME, {
-			name: "SAP AI Core (Foundation)",
-			baseUrl: "https://sap-aicore-handled-by-sdk.invalid",
-			apiKey: PLACEHOLDER_API_KEY,
-			api: FOUNDATION_PROVIDER_API,
-			models: foundationModels.map((m) =>
-				toPiModel(m, FOUNDATION_PROVIDER_API),
-			),
-			streamSimple: streamSapFoundation,
-		});
-	};
-
-	registerSapModelCommands(pi, registerProviders);
-	registerProviders();
+	const catalogController = createSapModelCatalogController();
+	const providers = createSapProviders(catalogController);
+
+	// coding-agent ships a nested exact pi-ai dependency, so strict resolvers can
+	// see two nominally distinct Provider type identities. The runtime contract is
+	// the same 0.81 object; isolate the package-boundary cast here.
+	const registerNativeProvider = pi.registerProvider.bind(pi) as unknown as (
+		provider: Provider,
+	) => void;
+	registerNativeProvider(providers.orchestration);
+	registerNativeProvider(providers.foundation);
+	registerSapModelCommands(pi, catalogController);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sap-aicore",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "SAP AI Core (orchestration + foundation) provider for the pi coding agent",
   "license": "MIT",
   "author": "Tim Pearson (https://github.com/ttiimmaahh)",
@@ -31,25 +31,26 @@
   },
   "scripts": {
     "update-models": "node scripts/update-models.mjs",
-    "test": "node scripts/test-auth-storage.mjs && node scripts/test-vertex-tool-schema.mjs && node scripts/test-bedrock-tool-results.mjs && node scripts/test-empty-content-blocks.mjs",
+    "test": "node scripts/test-auth-storage.mjs && node scripts/test-native-providers.mjs && node scripts/test-model-refresh.mjs && node scripts/test-vertex-tool-schema.mjs && node scripts/test-bedrock-tool-results.mjs && node scripts/test-empty-content-blocks.mjs",
     "validate:foundation": "node scripts/validate-foundation-executables.mjs",
     "prepublishOnly": "tsc --noEmit && npm test"
   },
   "dependencies": {
     "@sap-ai-sdk/ai-api": "^2.12.0",
+    "@sap-ai-sdk/core": "^2.12.0",
     "@sap-ai-sdk/foundation-models": "^2.12.0",
     "@sap-ai-sdk/orchestration": "^2.12.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.80.9",
-    "@earendil-works/pi-coding-agent": ">=0.80.9"
+    "@earendil-works/pi-ai": ">=0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.81.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.9",
-    "@earendil-works/pi-coding-agent": "^0.80.9",
+    "@earendil-works/pi-ai": "^0.81.0",
+    "@earendil-works/pi-coding-agent": "^0.81.0",
     "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
   }
 }

package/scripts/test-auth-storage.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// Offline regression test for sharing the orchestration provider's stored
-// subscription credential with the foundation provider. This makes no network
-// calls and uses an isolated temporary auth file.
+// Offline regression test for sharing the primary provider's stored service
+// key with the foundation provider. Makes no network calls and uses an
+// isolated temporary auth file.
 
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -10,7 +10,7 @@ import { pathToFileURL } from "node:url";
 
 const ROOT = new URL("..", import.meta.url).pathname;
 const { readSharedServiceKeyFromStore } = await import(
-	pathToFileURL(join(ROOT, "src/stream.ts")).href
+	pathToFileURL(join(ROOT, "src/auth.ts")).href
 );
 
 let failures = 0;
@@ -33,7 +33,7 @@ const tempDir = mkdtempSync(join(tmpdir(), "pi-sap-aicore-auth-"));
 const authPath = join(tempDir, "auth.json");
 
 try {
-	console.log("Shared OAuth credential lookup");
+	console.log("Legacy OAuth credential lookup");
 	writeFileSync(
 		authPath,
 		JSON.stringify({
@@ -48,41 +48,41 @@ try {
 	);
 	check(
 		readSharedServiceKeyFromStore(authPath) === serviceKey,
-		"reads the sap-aicore OAuth credential verbatim",
+		"reads the sap-aicore legacy credential verbatim",
 	);
 	check(
 		readSharedServiceKeyFromStore(authPath)?.includes("literal$secret"),
 		"preserves literal dollar signs",
 	);
 
+	console.log("Native API-key credential lookup");
+	writeFileSync(
+		authPath,
+		JSON.stringify({ "sap-aicore": { type: "api_key", key: serviceKey } }),
+	);
+	check(
+		readSharedServiceKeyFromStore(authPath) === serviceKey,
+		"reads the native Pi 0.81 API-key credential verbatim",
+	);
+
 	console.log("Provider isolation");
 	writeFileSync(
 		authPath,
-		JSON.stringify({
-			"another-provider": {
-				type: "oauth",
-				serviceKey,
-				access: "",
-				refresh: "",
-				expires: Number.MAX_SAFE_INTEGER,
-			},
-		}),
+		JSON.stringify({ "another-provider": { type: "api_key", key: serviceKey } }),
 	);
 	check(
 		readSharedServiceKeyFromStore(authPath) === undefined,
 		"does not borrow another provider's credential",
 	);
 
-	console.log("Credential type validation");
+	console.log("Credential validation");
 	writeFileSync(
 		authPath,
-		JSON.stringify({
-			"sap-aicore": { type: "api_key", key: serviceKey },
-		}),
+		JSON.stringify({ "sap-aicore": { type: "api_key", key: "not-json" } }),
 	);
 	check(
 		readSharedServiceKeyFromStore(authPath) === undefined,
-		"ignores non-OAuth credentials",
+		"ignores values that are not service-key JSON",
 	);
 } finally {
 	rmSync(tempDir, { recursive: true, force: true });

package/scripts/test-model-refresh.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+import { createSapModelCatalogController } from "../src/model-catalog-controller.ts";
+import { shouldUseCachedSnapshot } from "../src/model-catalog.ts";
+
+let failures = 0;
+function check(condition, message) {
+	if (condition) {
+		console.log(`  ✓ ${message}`);
+		return;
+	}
+	console.error(`  ❌ ${message}`);
+	failures++;
+}
+
+const sapModel = (id) => ({
+	id,
+	name: id,
+	reasoning: false,
+	tool_call: true,
+	temperature: true,
+	modalities: { input: ["text"], output: ["text"] },
+	limit: { context: 128000, output: 16384 },
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+});
+const loadedCatalog = (ids, cache) => ({
+	models: ids.map(sapModel),
+	foundationModelIds: new Set(ids.slice(0, 1)),
+	sources: { packaged: { models: ids.map(sapModel) }, cache },
+});
+
+console.log("Snapshot ordering");
+check(
+	!shouldUseCachedSnapshot(
+		{ fetchedAt: "2026-07-21T10:00:00.000Z", models: [sapModel("new")] },
+		{ fetchedAt: "2026-07-20T10:00:00.000Z", models: [sapModel("old")] },
+	),
+	"older persisted cache cannot override a newer bundled snapshot",
+);
+check(
+	shouldUseCachedSnapshot(
+		{ fetchedAt: "2026-07-20T10:00:00.000Z", models: [sapModel("old")] },
+		{ fetchedAt: "2026-07-21T10:00:00.000Z", models: [sapModel("new")] },
+	),
+	"newer cache overlays the bundled snapshot",
+);
+
+console.log("Freshness and forced refresh");
+const now = Date.parse("2026-07-21T12:00:00.000Z");
+let disk = loadedCatalog(["cached"], {
+	fetchedAt: "2026-07-21T11:00:00.000Z",
+	models: [sapModel("cached")],
+});
+let fetchCount = 0;
+const controller = createSapModelCatalogController({
+	loadCatalog: () => disk,
+	now: () => now,
+	fetchSnapshot: async () => {
+		fetchCount++;
+		return {
+			fetchedAt: "2026-07-21T12:00:00.000Z",
+			models: [sapModel("refreshed")],
+			count: 1,
+		};
+	},
+	writeSnapshot: (snapshot) => {
+		disk = loadedCatalog(
+			(snapshot.models ?? []).map((entry) => entry.id),
+			snapshot,
+		);
+	},
+});
+await controller.refresh({ allowNetwork: true });
+check(fetchCount === 0, "fresh cache suppresses automatic network refresh");
+await controller.refresh({ allowNetwork: true, force: true });
+check(fetchCount === 1, "forced refresh bypasses freshness gate");
+check(controller.getCatalog().models[0]?.id === "refreshed", "successful refresh publishes new models");
+
+console.log("Offline reload and cancellation");
+disk = loadedCatalog(["overlay-edit"], disk.sources.cache);
+await controller.refresh({ allowNetwork: false });
+check(controller.getCatalog().models[0]?.id === "overlay-edit", "offline refresh reloads local policy");
+const aborted = new AbortController();
+aborted.abort();
+await controller.refresh({ allowNetwork: true, force: true, signal: aborted.signal });
+check(fetchCount === 1, "already-aborted refresh performs no network request");
+
+console.log("Failure retention");
+const stable = loadedCatalog(["stable"], undefined);
+let failingDisk = stable;
+const failing = createSapModelCatalogController({
+	loadCatalog: () => failingDisk,
+	fetchSnapshot: async () => {
+		throw new Error("network down");
+	},
+	writeSnapshot: () => {
+		throw new Error("must not write");
+	},
+});
+failingDisk = loadedCatalog(["unpublished-local-reload"], undefined);
+try {
+	await failing.refresh({ allowNetwork: true, force: true });
+	check(false, "failed refresh rejects");
+} catch {
+	check(true, "failed refresh rejects");
+}
+check(failing.getCatalog().models[0]?.id === "stable", "failed online refresh retains published models");
+
+console.log("Incompatible cancellation signals");
+let cancellationFetchCount = 0;
+const cancelFirst = new AbortController();
+const cancellationSafe = createSapModelCatalogController({
+	loadCatalog: () => stable,
+	fetchSnapshot: (signal) => {
+		cancellationFetchCount++;
+		if (!signal) {
+			return Promise.resolve({
+				fetchedAt: new Date(now).toISOString(),
+				models: [sapModel("retry-after-cancel")],
+			});
+		}
+		return new Promise((_resolve, reject) => {
+			signal.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")), {
+				once: true,
+			});
+		});
+	},
+	writeSnapshot: () => {},
+});
+const cancelledRequest = cancellationSafe.refresh({
+	allowNetwork: true,
+	force: true,
+	signal: cancelFirst.signal,
+});
+const independentRequest = cancellationSafe.refresh({ allowNetwork: true, force: true });
+cancelFirst.abort();
+try {
+	await cancelledRequest;
+} catch {}
+await independentRequest;
+check(cancellationFetchCount === 2, "differently signaled callers get independent refresh attempts");
+
+console.log("Concurrent deduplication");
+let releaseFetch;
+let concurrentFetchCount = 0;
+const deferred = new Promise((resolve) => {
+	releaseFetch = resolve;
+});
+const concurrent = createSapModelCatalogController({
+	loadCatalog: () => stable,
+	fetchSnapshot: async () => {
+		concurrentFetchCount++;
+		await deferred;
+		return { fetchedAt: new Date(now).toISOString(), models: [sapModel("deduped")] };
+	},
+	writeSnapshot: () => {},
+});
+const first = concurrent.refresh({ allowNetwork: true, force: true });
+const second = concurrent.refresh({ allowNetwork: true, force: true });
+releaseFetch();
+await Promise.all([first, second]);
+check(concurrentFetchCount === 1, "simultaneous provider refreshes share one request");
+
+if (failures > 0) {
+	console.error(`\n${failures} check(s) failed`);
+	process.exit(1);
+}
+console.log("\nAll model refresh checks passed");