pi-sap-aicore 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-06
+
+### Added
+
+- User-refreshable SAP model catalog cache at
+  `~/.pi/agent/pi-sap-aicore/models-cache.json`.
+- Per-machine SAP model overlay at `~/.pi/agent/pi-sap-aicore/models.json`, with
+  support for `models`, `overrides`, `exclude`, and `foundation.enabledModelIds`.
+- `/sap-models` command family:
+  - `/sap-models update` refreshes public SAP model metadata without editing the
+    installed npm package.
+  - `/sap-models discover` compares the merged catalog against the SAP tenant's
+    `foundation-models` scenario model list.
+  - `/sap-models list`, `/sap-models paths`, and `/sap-models help` provide local
+    catalog diagnostics.
+
+### Changed
+
+- Model registration now merges packaged snapshot, user cache, and user overlay
+  at extension load time; `/sap-models update` re-registers providers in the
+  current session after refreshing the cache.
+- Foundation-route enablement is now configurable from the user overlay instead
+  of requiring source edits.
+
+## [0.1.2] - 2026-06-06
+
+### Added
+
+- Package-catalog preview image (`pi.image`) so the pi.dev gallery card shows a
+  `pi --list-models` screenshot.
+- Dependabot config: weekly grouped `npm` updates and `github-actions` updates.
+
+### Changed
+
+- CI: bump `actions/checkout` and `actions/setup-node` to v6 (off the deprecated
+  Node 20 action runtime).
+
 ## [0.1.1] - 2026-06-06
 
 ### Added
@@ -38,6 +75,8 @@ 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.1.1...HEAD
+[Unreleased]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/ttiimmaahh/pi-sap-aicore/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/ttiimmaahh/pi-sap-aicore/releases/tag/v0.1.0

package/README.md

@@ -141,18 +141,27 @@ that orchestration hasn't enabled streaming for yet (e.g. `gpt-5.5`).
 
 **Adding a foundation model:** it needs its own foundation-models deployment in
 SAP AI Core — one per (model, version, resource group); the SDK resolves it by
-model name, so no deployment IDs to wire in. Then add its `id` to
-`FOUNDATION_MODEL_IDS` in [`src/models-config.ts`](./src/models-config.ts)
-(definitions are reused from the shared snapshot). An id with no matching
-deployment 404s at call time. Run `node scripts/list-sap-models.mjs` to see what
-your tenant actually deploys.
+model name, so no deployment IDs to wire in. Then add its `id` to the per-machine
+extension overlay at `~/.pi/agent/pi-sap-aicore/models.json`:
+
+```json
+{
+  "foundation": { "enabledModelIds": ["gpt-5.5"] }
+}
+```
+
+Definitions are reused from the shared catalog, so an id only has to be present
+there. An id with no matching deployment 404s at call time. Run
+`/sap-models discover` in pi (or `node scripts/list-sap-models.mjs` from this
+repo) to see what your tenant actually deploys.
 
 ## Models
 
-The model list is composed of two sources, merged at startup:
+The model list is composed of three sources, merged at startup:
 
-1. **`src/models-snapshot.json`** — auto-generated from
-   [models.dev](https://models.dev)'s SAP AI Core catalog. Refresh with:
+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
    ```
@@ -160,15 +169,126 @@ The model list is composed of two sources, merged at startup:
    (currently anthropic claude-4.x, gpt-5*, gemini-2.5*), and writes the
    snapshot to disk. Commit the result.
 
-2. **`TENANT_EXTRAS` in [`src/models-config.ts`](./src/models-config.ts)** —
-   hand-maintained list of models that exist in your SAP tenant but
-   aren't (yet) in the models.dev catalog. Same `SapModel` shape. Extras
-   win over snapshot on duplicate `id`.
+2. **`~/.pi/agent/pi-sap-aicore/models-cache.json`** — per-machine public
+   catalog cache. Users refresh it 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.
+
+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,
+   model overrides, exclusions, and foundation-route enablement. Overlay models
+   win over cache/snapshot on duplicate `id`.
+
+Example overlay:
+
+```json
+{
+  "models": [
+    {
+      "id": "some-preview-model",
+      "name": "Some Preview Model",
+      "reasoning": true,
+      "tool_call": true,
+      "temperature": true,
+      "modalities": { "input": ["text"], "output": ["text"] },
+      "limit": { "context": 200000, "output": 32000 },
+      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+      "thinkingLevelMap": {
+        "minimal": "low",
+        "low": "low",
+        "medium": "medium",
+        "high": "high",
+        "xhigh": "high"
+      }
+    }
+  ],
+  "overrides": {
+    "gemini-2.5-pro": { "reasoning": false }
+  },
+  "exclude": ["gpt-5.5"],
+  "foundation": {
+    "enabledModelIds": ["some-preview-model"]
+  }
+}
+```
+
+Use `/sap-models paths` to print the exact cache and overlay paths, and
+`/sap-models discover` to compare the loaded catalog against the models your SAP
+tenant reports.
+
+### `/sap-models` commands
+
+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 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. |
+| `/sap-models help` | Shows the command summary in pi. |
+
+A typical refresh workflow is:
 
-To add a model that everyone on your team should see, add it to
-`TENANT_EXTRAS` and commit. To add a per-machine custom (your own tenant
-only), use pi's built-in custom-models mechanism by editing
-`~/.pi/agent/models.json` — no extension changes required.
+```text
+/sap-models update
+/sap-models discover
+/model
+```
+
+If `discover` reports a tenant model that is missing from the catalog, add it to
+`~/.pi/agent/pi-sap-aicore/models.json` under `models`. If it reports a catalog
+model that is absent from your tenant and selection causes SAP 400s, add the id
+to `exclude`.
+
+### Overlay reference
+
+`~/.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. |
+| `foundation.enabledModelIds` | `string[]` | Also exposes matching model ids through `sap-aicore-foundation/*`. Each id must exist in the merged catalog and have a foundation deployment in the selected resource group. |
+
+Minimal tenant-only model:
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-5.4-nano",
+      "name": "GPT-5.4 Nano",
+      "reasoning": true,
+      "tool_call": true,
+      "temperature": true,
+      "modalities": { "input": ["text", "image"], "output": ["text"] },
+      "limit": { "context": 1050000, "output": 128000 },
+      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+      "thinkingLevelMap": {
+        "minimal": "low",
+        "low": "low",
+        "medium": "medium",
+        "high": "high",
+        "xhigh": "high"
+      }
+    }
+  ]
+}
+```
+
+Minimal foundation enablement for a model already in the catalog:
+
+```json
+{
+  "foundation": { "enabledModelIds": ["gpt-5.5"] }
+}
+```
 
 The `cost` fields are vendor list prices (USD per million tokens) from
 models.dev. Used **only** for pi's in-UI cost display — your actual SAP
@@ -214,8 +334,8 @@ cycle is a no-op there. The models still reason (reasoning tokens are billed
 and show in `output`); the depth just isn't tunable. Use the orchestration
 route (`sap-aicore/*`) when you need to set the effort level.
 
-To override budgets per model, edit `thinkingLevelMap` on the relevant
-entry in `TENANT_EXTRAS`, or override per-user via pi's `models.json`.
+To override budgets per model, edit `thinkingLevelMap` on the relevant entry in
+`~/.pi/agent/pi-sap-aicore/models.json`.
 
 ## AI Resource Group
 
@@ -320,13 +440,15 @@ npmjs.com:
 │   └── publish.yml           # tag-driven npm publish via OIDC trusted publishing
 ├── index.ts                  # ExtensionAPI factory + registerProvider calls (both providers)
 ├── scripts/
-│   ├── update-models.mjs     # fetches models.dev, writes models-snapshot.json
+│   ├── 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
 └── src/
     ├── auth.ts                  # service-key validation + pi oauth registration
-    ├── models-config.ts         # loads snapshot, merges TENANT_EXTRAS, exposes FOUNDATION_MODELS
+    ├── model-catalog.ts         # loads snapshot/cache/overlay and adapts models.dev metadata
+    ├── models-config.ts         # exposes merged MODELS and FOUNDATION_MODELS
     ├── models-snapshot.json     # auto-generated from models.dev (committed)
+    ├── 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)
     ├── translate.ts             # pi Context ↔ orchestration message shape

package/index.ts

@@ -2,7 +2,8 @@ import type { Api } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { sapAiCoreOAuth } from "./src/auth.ts";
-import { FOUNDATION_MODELS, MODELS } from "./src/models-config.ts";
+import { loadModelCatalog } from "./src/model-catalog.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";
@@ -25,44 +26,57 @@ const FOUNDATION_PROVIDER_API = "sap-aicore-foundation" as Api;
 const PLACEHOLDER_API_KEY = "managed-by-extension-oauth";
 
 export default function (pi: ExtensionAPI) {
-	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,
-	});
+	const registerProviders = () => {
+		const catalog = loadModelCatalog();
+		const models = catalog.models;
+		const foundationModels = models.filter((m) =>
+			catalog.foundationModelIds.has(m.id),
+		);
 
-	// Foundation provider — shares the exact same credential. Both providers
-	// reference the same `sapAiCoreOAuth` (oauth name "SAP AI Core"), so a single
-	// `/login` serves both and the service key is never entered twice. 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,
-		oauth: sapAiCoreOAuth,
-		models: FOUNDATION_MODELS.map((m) => toPiModel(m, FOUNDATION_PROVIDER_API)),
-		streamSimple: streamSapFoundation,
-	});
+		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. Both providers
+		// reference the same `sapAiCoreOAuth` (oauth name "SAP AI Core"), so a single
+		// `/login` serves both and the service key is never entered twice. 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,
+			oauth: sapAiCoreOAuth,
+			models: foundationModels.map((m) =>
+				toPiModel(m, FOUNDATION_PROVIDER_API),
+			),
+			streamSimple: streamSapFoundation,
+		});
+	};
+
+	registerSapModelCommands(pi, registerProviders);
+	registerProviders();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sap-aicore",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "SAP AI Core (orchestration + foundation) provider for the pi coding agent",
   "license": "MIT",
   "author": "Tim Pearson (https://github.com/ttiimmaahh)",
@@ -26,13 +26,15 @@
   "pi": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/ttiimmaahh/pi-sap-aicore/main/docs/sap-model-list.jpg"
   },
   "scripts": {
     "update-models": "node scripts/update-models.mjs",
     "prepublishOnly": "tsc --noEmit"
   },
   "dependencies": {
+    "@sap-ai-sdk/ai-api": "^2.10.0",
     "@sap-ai-sdk/foundation-models": "^2.10.0",
     "@sap-ai-sdk/orchestration": "^2.10.0"
   },
@@ -43,7 +45,7 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.78.0",
     "@earendil-works/pi-coding-agent": "^0.78.0",
-    "typescript": "^5.6.0"
+    "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=20"

package/scripts/update-models.mjs

@@ -12,11 +12,9 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const OUT = join(__dirname, "..", "src", "models-snapshot.json");
 const SOURCE = "https://models.dev/api.json";
 
-// SAP orchestration uses provider-native reasoning shapes (see
-// src/stream.ts:reasoningParams). What's *common* across providers is the
-// effort tier — pi has 5 above-off levels, the provider tiers are 3
-// (low/medium/high). Fold minimal→low and xhigh→high so every pi level
-// still does something (rather than dropping minimal/xhigh silently).
+// Keep this script self-contained instead of importing src/model-catalog.ts so
+// `npm run update-models` works on every supported Node >=20 runtime. pi loads
+// extension TypeScript through jiti, but plain Node 20 does not import .ts files.
 const SAP_EFFORT_BY_LEVEL = {
 	minimal: "low",
 	low: "low",

package/src/model-catalog.ts

@@ -0,0 +1,291 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type ThinkingLevel =
+	| "off"
+	| "minimal"
+	| "low"
+	| "medium"
+	| "high"
+	| "xhigh";
+
+export type SapModel = {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	tool_call: boolean;
+	temperature: boolean;
+	modalities: {
+		input: ("text" | "image" | "pdf")[];
+		output: "text"[];
+	};
+	limit: {
+		context: number;
+		output: number;
+	};
+	cost: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+	};
+	thinkingLevelMap?: Partial<Record<ThinkingLevel, string | null>>;
+};
+
+export type SapModelOverlay = {
+	models?: SapModel[];
+	overrides?: Record<string, Partial<SapModel>>;
+	exclude?: string[];
+	foundation?: {
+		enabledModelIds?: string[];
+	};
+};
+
+export type SapModelsSnapshot = {
+	source?: string;
+	fetchedAt?: string;
+	count?: number;
+	models?: SapModel[];
+};
+
+export const MODELS_DEV_SOURCE = "https://models.dev/api.json";
+export const DEFAULT_FOUNDATION_MODEL_IDS = ["gpt-5.5"] as const;
+
+const SAP_EFFORT_BY_LEVEL: SapModel["thinkingLevelMap"] = {
+	minimal: "low",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "high",
+};
+
+function packageDir(): string {
+	return dirname(fileURLToPath(import.meta.url));
+}
+
+export function sapModelsDir(): string {
+	return join(getAgentDir(), "pi-sap-aicore");
+}
+
+export function userOverlayPath(): string {
+	return join(sapModelsDir(), "models.json");
+}
+
+export function userCachePath(): string {
+	return join(sapModelsDir(), "models-cache.json");
+}
+
+export function packagedSnapshotPath(): string {
+	return join(packageDir(), "models-snapshot.json");
+}
+
+export function readJsonFile<T>(path: string): T | undefined {
+	if (!existsSync(path)) return undefined;
+	return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+function readUserJsonFile<T>(path: string, label: string): T | undefined {
+	try {
+		return readJsonFile<T>(path);
+	} catch (error) {
+		console.warn(
+			`Ignoring invalid pi-sap-aicore ${label} file at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return undefined;
+	}
+}
+
+export function writeJsonFile(path: string, value: unknown): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function loadPackagedSnapshot(): SapModelsSnapshot {
+	return (
+		readJsonFile<SapModelsSnapshot>(packagedSnapshotPath()) ?? { models: [] }
+	);
+}
+
+export function loadUserCache(): SapModelsSnapshot | undefined {
+	return readUserJsonFile<SapModelsSnapshot>(userCachePath(), "cache");
+}
+
+export function loadUserOverlay(): SapModelOverlay | undefined {
+	const overlay = readUserJsonFile<SapModelOverlay>(
+		userOverlayPath(),
+		"overlay",
+	);
+	if (!overlay) return undefined;
+	return {
+		...overlay,
+		models: overlay.models ?? [],
+		overrides: overlay.overrides ?? {},
+		exclude: overlay.exclude ?? [],
+		foundation: {
+			...overlay.foundation,
+			enabledModelIds: overlay.foundation?.enabledModelIds ?? [],
+		},
+	};
+}
+
+function mergeModel(base: SapModel, override: Partial<SapModel>): SapModel {
+	return {
+		...base,
+		...override,
+		modalities: override.modalities
+			? {
+					input: override.modalities.input ?? base.modalities.input,
+					output: override.modalities.output ?? base.modalities.output,
+				}
+			: base.modalities,
+		limit: override.limit ? { ...base.limit, ...override.limit } : base.limit,
+		cost: override.cost ? { ...base.cost, ...override.cost } : base.cost,
+		thinkingLevelMap: override.thinkingLevelMap
+			? { ...base.thinkingLevelMap, ...override.thinkingLevelMap }
+			: base.thinkingLevelMap,
+	};
+}
+
+export function mergeSapModels(options: {
+	packaged: SapModel[];
+	cache?: SapModel[];
+	overlay?: SapModelOverlay;
+}): SapModel[] {
+	const byId = new Map<string, SapModel>();
+	for (const model of options.packaged) byId.set(model.id, model);
+	for (const model of options.cache ?? []) byId.set(model.id, model);
+	for (const model of options.overlay?.models ?? []) byId.set(model.id, model);
+
+	for (const [id, override] of Object.entries(
+		options.overlay?.overrides ?? {},
+	)) {
+		const existing = byId.get(id);
+		if (existing) byId.set(id, mergeModel(existing, override));
+	}
+
+	for (const id of options.overlay?.exclude ?? []) byId.delete(id);
+
+	return Array.from(byId.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function loadModelCatalog(): {
+	models: SapModel[];
+	foundationModelIds: Set<string>;
+	sources: {
+		packaged: SapModelsSnapshot;
+		cache?: SapModelsSnapshot;
+		overlay?: SapModelOverlay;
+	};
+} {
+	const packaged = loadPackagedSnapshot();
+	const cache = loadUserCache();
+	const overlay = loadUserOverlay();
+	const models = mergeSapModels({
+		packaged: packaged.models ?? [],
+		cache: cache?.models,
+		overlay,
+	});
+	const foundationModelIds = new Set([
+		...DEFAULT_FOUNDATION_MODEL_IDS,
+		...(overlay?.foundation?.enabledModelIds ?? []),
+	]);
+	return { models, foundationModelIds, sources: { packaged, cache, overlay } };
+}
+
+function thinkingMapFor(
+	reasoning: boolean,
+): SapModel["thinkingLevelMap"] | undefined {
+	return reasoning ? { ...SAP_EFFORT_BY_LEVEL } : undefined;
+}
+
+function supportsReasoning(model: {
+	id: string;
+	reasoning?: boolean;
+}): boolean {
+	if (!model.reasoning) return false;
+	if (model.id.startsWith("gemini-")) return false;
+	return true;
+}
+
+export function adaptModelsDevModel(model: {
+	id: string;
+	name?: string;
+	reasoning?: boolean;
+	tool_call?: boolean;
+	temperature?: boolean;
+	modalities?: { input?: string[] };
+	limit?: { context?: number; output?: number };
+	cost?: {
+		input?: number;
+		output?: number;
+		cache_read?: number;
+		cache_write?: number;
+	};
+}): SapModel {
+	const input = (model.modalities?.input ?? ["text"]).filter(
+		(m): m is "text" | "image" | "pdf" =>
+			m === "text" || m === "image" || m === "pdf",
+	);
+	const reasoning = supportsReasoning(model);
+	const adapted: SapModel = {
+		id: model.id,
+		name: model.name ?? model.id,
+		reasoning,
+		tool_call: !!model.tool_call,
+		temperature: model.temperature !== false,
+		modalities: {
+			input,
+			output: ["text"],
+		},
+		limit: {
+			context: model.limit?.context ?? 0,
+			output: model.limit?.output ?? 0,
+		},
+		cost: {
+			input: model.cost?.input ?? 0,
+			output: model.cost?.output ?? 0,
+			cacheRead: model.cost?.cache_read ?? 0,
+			cacheWrite: model.cost?.cache_write ?? 0,
+		},
+	};
+	const thinkingMap = thinkingMapFor(reasoning);
+	if (thinkingMap) adapted.thinkingLevelMap = thinkingMap;
+	return adapted;
+}
+
+export function shouldIncludeModelsDevModel(id: string): boolean {
+	return (
+		id.startsWith("anthropic--claude-4") ||
+		id.startsWith("gpt-5") ||
+		id.startsWith("gemini-2.5")
+	);
+}
+
+export async function fetchModelsDevSapSnapshot(): Promise<SapModelsSnapshot> {
+	const res = await fetch(MODELS_DEV_SOURCE);
+	if (!res.ok) {
+		throw new Error(
+			`Failed to fetch ${MODELS_DEV_SOURCE}: ${res.status} ${res.statusText}`,
+		);
+	}
+	const all = (await res.json()) as {
+		"sap-ai-core"?: {
+			models?: Record<string, Parameters<typeof adaptModelsDevModel>[0]>;
+		};
+	};
+	const sapModels = all["sap-ai-core"]?.models ?? {};
+	const adapted = Object.values(sapModels)
+		.filter((m) => shouldIncludeModelsDevModel(m.id))
+		.map(adaptModelsDevModel)
+		.sort((a, b) => a.id.localeCompare(b.id));
+
+	return {
+		source: MODELS_DEV_SOURCE,
+		fetchedAt: new Date().toISOString(),
+		count: adapted.length,
+		models: adapted,
+	};
+}

package/src/models-config.ts

@@ -1,92 +1,29 @@
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import {
+	DEFAULT_FOUNDATION_MODEL_IDS,
+	loadModelCatalog,
+	type SapModel,
+} from "./model-catalog.ts";
 
-type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type { SapModel } from "./model-catalog.ts";
 
-export type SapModel = {
-	id: string;
-	name: string;
-	reasoning: boolean;
-	tool_call: boolean;
-	temperature: boolean;
-	modalities: {
-		input: ("text" | "image" | "pdf")[];
-		output: ("text")[];
-	};
-	limit: {
-		context: number;
-		output: number;
-	};
-	cost: {
-		input: number;
-		output: number;
-		cacheRead: number;
-		cacheWrite: number;
-	};
-	thinkingLevelMap?: Partial<Record<ThinkingLevel, string | null>>;
-};
+const catalog = loadModelCatalog();
 
-// Tenant-specific or pre-release models not yet in models.dev's SAP catalog.
-// Anything in your SAP tenant that the snapshot doesn't include — add here.
-// User-side additions (per-machine, not in source control) should go in
-// ~/.pi/agent/models.json using pi's built-in custom-models mechanism.
-// SAP orchestration unifies reasoning across providers as
-// output_config.effort: "low" | "medium" | "high". See scripts/update-models.mjs
-// and stream.ts for the full mapping rationale.
-const SAP_EFFORT: SapModel["thinkingLevelMap"] = {
-	minimal: "low",
-	low: "low",
-	medium: "medium",
-	high: "high",
-	xhigh: "high",
-};
-
-// Currently empty — models.dev's SAP catalog covers everything in our
-// tenant. Add entries here when SAP exposes a tenant-only or pre-release
-// model that hasn't landed in the public catalog yet, e.g.:
-//
-//   {
-//     id: "some-preview-model",
-//     name: "Some Preview Model",
-//     reasoning: true,
-//     tool_call: true,
-//     temperature: true,
-//     modalities: { input: ["text"], output: ["text"] },
-//     limit: { context: 200_000, output: 32_000 },
-//     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-//     thinkingLevelMap: SAP_EFFORT,
-//   },
-const TENANT_EXTRAS: SapModel[] = [];
-
-function loadSnapshot(): SapModel[] {
-	const snapshotPath = join(
-		dirname(fileURLToPath(import.meta.url)),
-		"models-snapshot.json",
-	);
-	const raw = readFileSync(snapshotPath, "utf8");
-	const parsed = JSON.parse(raw) as { models?: SapModel[] };
-	return parsed.models ?? [];
-}
-
-const SNAPSHOT_MODELS = loadSnapshot();
-
-// Merge: snapshot first, then extras (extras win on duplicate id).
-const byId = new Map<string, SapModel>();
-for (const m of SNAPSHOT_MODELS) byId.set(m.id, m);
-for (const m of TENANT_EXTRAS) byId.set(m.id, m);
-
-export const MODELS: SapModel[] = Array.from(byId.values()).sort((a, b) =>
-	a.id.localeCompare(b.id),
-);
+export const MODELS: SapModel[] = catalog.models;
 
 // Models exposed via the direct *foundation* (Azure OpenAI) provider, which
 // routes through a per-model SAP AI Core deployment instead of orchestration.
 // List ONLY ids you've created a foundation-models deployment for — SAP needs
 // one deployment per (model, version, resource group), and an id with no
 // deployment 404s at call time. Definitions (cost/limits/modalities) are reused
-// from the shared snapshot above, so an id only has to be present there.
-const FOUNDATION_MODEL_IDS = new Set(["gpt-5.5"]);
+// from the shared catalog above, so an id only has to be present there.
+//
+// Per-machine additions should go in:
+//   ~/.pi/agent/pi-sap-aicore/models.json
+//
+// Example:
+//   { "foundation": { "enabledModelIds": ["gpt-5.5"] } }
+export const FOUNDATION_MODEL_IDS = catalog.foundationModelIds;
+export const DEFAULT_FOUNDATION_IDS = DEFAULT_FOUNDATION_MODEL_IDS;
 
 export const FOUNDATION_MODELS: SapModel[] = MODELS.filter((m) =>
 	FOUNDATION_MODEL_IDS.has(m.id),

package/src/sap-model-commands.ts

@@ -0,0 +1,149 @@
+import {
+	AuthStorage,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { ScenarioApi } from "@sap-ai-sdk/ai-api";
+
+import { parseAndValidateServiceKey } from "./auth.ts";
+import {
+	fetchModelsDevSapSnapshot,
+	loadModelCatalog,
+	userCachePath,
+	userOverlayPath,
+	writeJsonFile,
+} from "./model-catalog.ts";
+import { ensureServiceKey, resolveResourceGroup } from "./stream.ts";
+
+function sharedServiceKeyFromAuthStore(): string | undefined {
+	try {
+		const store = AuthStorage.create();
+		for (const provider of store.list()) {
+			const cred = store.get(provider);
+			if (cred?.type !== "oauth") continue;
+			const serviceKey = (cred as { serviceKey?: unknown }).serviceKey;
+			if (
+				typeof serviceKey === "string" &&
+				serviceKey.trimStart().startsWith("{")
+			) {
+				return serviceKey;
+			}
+		}
+	} catch {
+		// Let callers produce the actionable no-key message.
+	}
+	return undefined;
+}
+
+function resolveCommandServiceKey(): ReturnType<
+	typeof parseAndValidateServiceKey
+> {
+	const raw = process.env.AICORE_SERVICE_KEY ?? sharedServiceKeyFromAuthStore();
+	return ensureServiceKey(raw);
+}
+
+function formatModelList(ids: string[], max = 30): string {
+	if (ids.length === 0) return "none";
+	const head = ids.slice(0, max).join(", ");
+	const rest = ids.length > max ? ` … +${ids.length - max} more` : "";
+	return `${head}${rest}`;
+}
+
+async function tenantModelIds(): Promise<Set<string>> {
+	const key = resolveCommandServiceKey();
+	parseAndValidateServiceKey(key.raw);
+	process.env.AICORE_SERVICE_KEY = key.raw;
+	const resourceGroup = resolveResourceGroup(key) ?? "default";
+	const response = await ScenarioApi.scenarioQueryModels("foundation-models", {
+		"AI-Resource-Group": resourceGroup,
+	}).execute();
+	const resources = response?.resources ?? [];
+	return new Set(resources.map((r) => r.model));
+}
+
+export function registerSapModelCommands(
+	pi: ExtensionAPI,
+	onModelsChanged?: () => void,
+): void {
+	pi.registerCommand("sap-models", {
+		description:
+			"Manage pi-sap-aicore model metadata: update, discover, list, paths",
+		getArgumentCompletions: (prefix) => {
+			const commands = ["update", "discover", "list", "paths", "help"];
+			const items = commands.map((command) => ({
+				value: command,
+				label: command,
+			}));
+			const filtered = items.filter((item) =>
+				item.value.startsWith(prefix.trim()),
+			);
+			return filtered.length > 0 ? filtered : items;
+		},
+		handler: async (args, ctx) => {
+			const [subcommand = "help"] = args.trim().split(/\s+/, 1);
+			try {
+				switch (subcommand) {
+					case "update": {
+						ctx.ui.setStatus("sap-models", "updating model cache…");
+						const snapshot = await fetchModelsDevSapSnapshot();
+						writeJsonFile(userCachePath(), snapshot);
+						onModelsChanged?.();
+						ctx.ui.notify(
+							`Updated SAP model cache: ${snapshot.count ?? snapshot.models?.length ?? 0} models. Refreshed sap-aicore providers for this session.`,
+							"info",
+						);
+						ctx.ui.setStatus("sap-models", undefined);
+						return;
+					}
+					case "discover": {
+						ctx.ui.setStatus("sap-models", "querying SAP tenant…");
+						const tenant = await tenantModelIds();
+						const catalog = loadModelCatalog();
+						const known = new Set(catalog.models.map((m) => m.id));
+						const tenantSorted = [...tenant].sort();
+						const missing = tenantSorted.filter((id) => !known.has(id));
+						const phantom = catalog.models
+							.map((m) => m.id)
+							.filter((id) => !tenant.has(id))
+							.sort();
+						ctx.ui.notify(
+							`SAP tenant discovery: ${tenant.size} tenant models. Missing from pi-sap-aicore catalog: ${formatModelList(missing)}. In catalog but absent from tenant: ${formatModelList(phantom)}.`,
+							missing.length > 0 || phantom.length > 0 ? "warning" : "info",
+						);
+						ctx.ui.setStatus("sap-models", undefined);
+						return;
+					}
+					case "list": {
+						const catalog = loadModelCatalog();
+						ctx.ui.notify(
+							`pi-sap-aicore catalog has ${catalog.models.length} orchestration models and ${catalog.models.filter((m) => catalog.foundationModelIds.has(m.id)).length} foundation-enabled models.`,
+							"info",
+						);
+						return;
+					}
+					case "paths": {
+						ctx.ui.notify(
+							`SAP model files:\ncache: ${userCachePath()}\noverlay: ${userOverlayPath()}`,
+							"info",
+						);
+						return;
+					}
+					case "help":
+					default:
+						ctx.ui.notify(
+							"/sap-models update — refresh public SAP model metadata\n" +
+								"/sap-models discover — compare catalog against your SAP tenant\n" +
+								"/sap-models list — summarize loaded catalog\n" +
+								"/sap-models paths — show user cache/overlay paths",
+							"info",
+						);
+				}
+			} catch (error) {
+				ctx.ui.setStatus("sap-models", undefined);
+				ctx.ui.notify(
+					`SAP model command failed: ${error instanceof Error ? error.message : String(error)}`,
+					"error",
+				);
+			}
+		},
+	});
+}