pi-private-models 0.1.0

package/LICENSE

@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from your organization if needed.
+
+   Copyright 2025 the contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,42 @@
+# pi-private-models
+
+**English** | [简体中文](./README.zh-CN.md)
+
+pi extension that keeps private model providers out of the published `models.json`
+
+```
+<agent-dir>/models.json          public, committed
+<agent-dir>/models.private.json  private, kept out of the repository
+```
+
+```jsonc
+{
+  "providers": {
+    "my-gateway": {
+      "baseUrl": "http://10.0.0.5:8123/v1",
+      "api": "openai-completions",
+      "apiKey": "$GATEWAY_API_KEY",
+      "models": [
+        { "id": "glm-5.3", "reasoning": true, "contextWindow": 200000, "maxTokens": 32000 },
+        // ...
+      ]
+    }
+  }
+}
+```
+
+## Install
+
+From npmjs:
+
+```bash
+pi install npm:pi-private-models
+```
+
+From GitHub:
+
+```bash
+pi install git:github.com/jalaxy33/pi-private-models
+```
+
+Add `models.private.json` to your `.gitignore`. A missing file does nothing.

package/README.zh-CN.md

@@ -0,0 +1,42 @@
+# pi-private-models
+
+[English](./README.md) | **简体中文**
+
+pi 扩展，让私有模型 provider 不进公开的 `models.json`
+
+```
+<agent-dir>/models.json          公开，提交进仓库
+<agent-dir>/models.private.json  私有，不进仓库
+```
+
+```jsonc
+{
+  "providers": {
+    "my-gateway": {
+      "baseUrl": "http://10.0.0.5:8123/v1",
+      "api": "openai-completions",
+      "apiKey": "$GATEWAY_API_KEY",
+      "models": [
+        { "id": "glm-5.3", "reasoning": true, "contextWindow": 200000, "maxTokens": 32000 },
+        // ……
+      ]
+    }
+  }
+}
+```
+
+## 安装
+
+从 npmjs 安装：
+
+```bash
+pi install npm:pi-private-models
+```
+
+从 GitHub 安装：
+
+```bash
+pi install git:github.com/jalaxy33/pi-private-models
+```
+
+记得把 `models.private.json` 加进 `.gitignore`。文件不存在就什么都不做。

package/extensions/private-models/apply.ts

@@ -0,0 +1,87 @@
+/**
+ * Turn models.private.json into provider registrations.
+ *
+ * Runs twice: while extensions load, when there is no runtime yet and inherit
+ * targets come from the files, and at session start, when pi's own model store
+ * can answer for the catalog and for models.json.
+ */
+import { readAgentJson, type Dict } from "./utils/read-agent-json.ts";
+import { withDefaults } from "./defaults.ts";
+import { parsePrivateFile, readPrivateFile } from "./private-file.ts";
+import { fileLookup, planInherit, providerIdsOf, storeLookup, withModelDefaults } from "./resolve-inherit.ts";
+
+/** The two provider calls this extension makes. */
+export interface Registrations {
+	register(providerId: string, config: Dict): void;
+	unregister(providerId: string): void;
+}
+
+/**
+ * Applies the private file and returns what is wrong with it. `registered` holds
+ * the ids this extension owns, and is kept up to date.
+ */
+export function applyPrivateProviders(registrations: Registrations, registered: Set<string>, runtime: any | undefined): string[] {
+	const publicFile = readAgentJson("models.json");
+	const parsed = parsePrivateFile(readPrivateFile());
+	const issues = [...parsed.issues];
+
+	const lookup = runtime ? storeLookup(parsed.providers, runtime) : fileLookup(parsed.providers, publicFile);
+	const knownProviders = new Set([...parsed.providers.keys(), ...providerIdsOf(publicFile), ...runtimeProviderIds(runtime)]);
+	const plan = planInherit(parsed.providers, lookup, knownProviders);
+	issues.push(...plan.issues);
+	// Without a runtime a catalog model is simply not there yet, so wait for the next run.
+	if (runtime) issues.push(...plan.unresolved);
+
+	const taken = takenIds(runtime, registered);
+	const next = new Set<string>();
+	for (const [providerId, provider] of parsed.providers) {
+		const conflict = taken.get(providerId);
+		if (conflict) {
+			issues.push(`providers["${providerId}"] is ignored: "${providerId}" is ${conflict}.`);
+			continue;
+		}
+		const { config, models } = withDefaults(provider.config, plan.models.get(providerId) ?? provider.models, parsed.defaults, providerId);
+		const missing = ["baseUrl", "api"].filter((key) => typeof config[key] !== "string" || config[key] === "");
+		if (missing.length > 0) {
+			issues.push(`providers["${providerId}"] needs ${missing.map((key) => `"${key}"`).join(" and ")}: this extension registers it, so it has to carry them.`);
+			continue;
+		}
+		try {
+			registrations.register(providerId, { ...config, models: models.map(withModelDefaults) });
+			next.add(providerId);
+		} catch (error) {
+			issues.push(`providers["${providerId}"]: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	for (const providerId of [...registered]) if (!next.has(providerId)) registrations.unregister(providerId);
+	registered.clear();
+	for (const providerId of next) registered.add(providerId);
+	return issues;
+}
+
+/** Why a private id must stay away: that id belongs to pi, or to another extension. */
+function takenIds(runtime: any | undefined, ours: ReadonlySet<string>): Map<string, string> {
+	const taken = new Map<string, string>();
+	const add = (providerId: string, reason: string): void => {
+		if (!taken.has(providerId)) taken.set(providerId, reason);
+	};
+	for (const providerId of providerIdsOf(readAgentJson("models.json"))) add(providerId, "defined in models.json");
+	for (const providerId of runtime?.builtins?.keys?.() ?? []) add(String(providerId), "a built-in provider");
+	for (const map of [runtime?.nativeExtensionProviders, runtime?.extensionProviders]) {
+		for (const providerId of map?.keys?.() ?? []) {
+			if (ours.has(String(providerId))) continue; // our own registration
+			add(String(providerId), "registered by another extension");
+		}
+	}
+	return taken;
+}
+
+/** Provider ids pi knows once it is running: built-ins, models.json, extensions. */
+function runtimeProviderIds(runtime: any | undefined): string[] {
+	const ids = new Set<string>();
+	for (const map of [runtime?.builtins, runtime?.nativeExtensionProviders, runtime?.extensionProviders]) {
+		for (const providerId of map?.keys?.() ?? []) ids.add(String(providerId));
+	}
+	for (const providerId of runtime?.config?.getProviderIds?.() ?? []) ids.add(String(providerId));
+	return [...ids];
+}

package/extensions/private-models/defaults.ts

@@ -0,0 +1,46 @@
+/**
+ * The `default` block of models.private.json: values the providers of that file
+ * inherit. Applied here, while building the registration, so they never reach a
+ * provider that is defined somewhere else.
+ */
+import { isObj, type Dict } from "./utils/read-agent-json.ts";
+import { merge, pick } from "./utils/fields.ts";
+
+/** Keys pi reads while composing a provider, so they belong on the provider config. */
+const CONFIG_KEYS = ["name", "baseUrl", "apiKey", "api", "authHeader"];
+
+export interface PrivateDefaults {
+	star?: Dict;
+	exact: Map<string, Dict>;
+}
+
+export const noDefaults = (): PrivateDefaults => ({ exact: new Map() });
+
+/** `"*"` first, then the exact provider id. */
+export function defaultsFor(defaults: PrivateDefaults, providerId: string): Dict | undefined {
+	const star = defaults.star;
+	const exact = defaults.exact.get(providerId);
+	if (!star) return exact;
+	if (!exact) return star;
+	return merge(star, exact);
+}
+
+/**
+ * Provider config with the default block under the provider's own values.
+ *
+ * `compat` is handed down to every model entry: pi drops provider-level compat
+ * for providers that an extension registers, so the entry is the only place it counts.
+ */
+export function withDefaults(config: Dict, models: Dict[], defaults: PrivateDefaults, providerId: string): { config: Dict; models: Dict[] } {
+	const layer = defaultsFor(defaults, providerId);
+	const compat = merge(isObj(layer?.compat) ? layer.compat : {}, isObj(config.compat) ? config.compat : {});
+	const merged = merge(pick(layer, CONFIG_KEYS) ?? {}, config);
+	delete merged.compat;
+	if (isObj(layer?.headers)) merged.headers = merge(layer.headers, isObj(config.headers) ? config.headers : {});
+	return {
+		config: merged,
+		models: Object.keys(compat).length > 0
+			? models.map((entry) => ({ ...entry, compat: merge(compat, isObj(entry.compat) ? entry.compat : {}) }))
+			: models,
+	};
+}

package/extensions/private-models/index.ts

@@ -0,0 +1,88 @@
+/**
+ * pi-private-models: the providers of `models.private.json`, a file next to the
+ * models.json that gets published.
+ *
+ *   models.json          public, committed
+ *   models.private.json  private, kept out of the repository
+ *
+ * The private file only adds providers. An id that already belongs to pi or to
+ * another extension is ignored, and nothing is written back.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readAgentJson } from "./utils/read-agent-json.ts";
+import { applyPrivateProviders, type Registrations } from "./apply.ts";
+import { LOCAL_KEYS } from "./resolve-inherit.ts";
+
+const LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+type Level = (typeof LEVELS)[number];
+const isLevel = (value: unknown): value is Level => typeof value === "string" && (LEVELS as readonly string[]).includes(value);
+
+export default function piPrivateModels(pi: ExtensionAPI): void {
+	const registered = new Set<string>();
+	const warned = new Set<string>();
+	const registrations: Registrations = {
+		register: (providerId, config) => pi.registerProvider(providerId, config as any),
+		unregister: (providerId) => pi.unregisterProvider(providerId),
+	};
+
+	// Register the file before pi picks the startup model, so model selection and
+	// --list-models already see the private providers. Without a runtime only the
+	// files can answer `inherit`, so the values may still change at session start.
+	applyPrivateProviders(registrations, registered, undefined);
+
+	/**
+	 * pi resolves the session's thinking level from settings while it builds the
+	 * startup model, before the private provider exists, so a model that only
+	 * becomes reasoning-capable through `inherit` starts at a level clamped to
+	 * "off". An endpoint that rejects `thinking: {"type":"disabled"}` then fails
+	 * every request, so put back the level pi would have chosen.
+	 */
+	const restoreThinkingLevel = (model: any): void => {
+		if (model?.reasoning !== true || pi.getThinkingLevel?.() !== "off") return;
+		const settings = readAgentJson("settings.json");
+		const level = settings?.modelThinkingLevels?.[`${model.provider}/${model.id}`] ?? settings?.defaultThinkingLevel ?? "medium";
+		if (!isLevel(level) || level === "off") return;
+		try {
+			pi.setThinkingLevel(level);
+		} catch {
+			/* no session runtime: nothing to restore */
+		}
+	};
+
+	/**
+	 * A model resolved before this extension re-registered its provider keeps the
+	 * object it was built with, so copy the fields of the freshly composed one.
+	 */
+	const adopt = (ctx: any): void => {
+		const model = ctx?.model;
+		if (!model || !registered.has(model.provider)) return;
+		const fresh = ctx?.modelRegistry?.runtime?.models?.getModel?.(model.provider, model.id);
+		if (fresh && fresh !== model) {
+			for (const [key, value] of Object.entries(fresh)) {
+				if (LOCAL_KEYS.includes(key)) continue;
+				try {
+					model[key] = value;
+				} catch {
+					/* frozen: the store copy is still correct */
+				}
+			}
+		}
+		restoreThinkingLevel(model);
+	};
+
+	const warn = (ctx: any, issues: string[]): void => {
+		if (issues.length === 0) return;
+		const message = `pi-private-models: ${issues.join(" ")}`;
+		if (warned.has(message)) return;
+		warned.add(message);
+		if (ctx?.hasUI && typeof ctx.ui?.notify === "function") ctx.ui.notify(message, "warning");
+	};
+
+	const sync = (ctx: any): void => {
+		warn(ctx, applyPrivateProviders(registrations, registered, ctx?.modelRegistry?.runtime));
+		adopt(ctx);
+	};
+
+	pi.on("session_start", (_event, ctx) => sync(ctx));
+	pi.on("model_select", (_event, ctx) => sync(ctx));
+}

package/extensions/private-models/private-file.ts

@@ -0,0 +1,221 @@
+/**
+ * models.private.json: the same shape as models.json, read by this extension
+ * instead of by pi. It only adds providers; a key that would change a provider
+ * defined elsewhere is refused.
+ */
+import { isObj, readAgentJson, type Dict } from "./utils/read-agent-json.ts";
+import { suggest } from "./utils/suggest.ts";
+import { noDefaults, type PrivateDefaults } from "./defaults.ts";
+
+export const PRIVATE_FILE = "models.private.json";
+
+/** Parsed `<agentDir>/models.private.json`, or undefined when there is no such file. */
+export const readPrivateFile = (): Dict | undefined => readAgentJson(PRIVATE_FILE);
+
+export interface PrivateProvider {
+	/** Provider config as written, without `models`. */
+	config: Dict;
+	/** Model entries as written, `inherit` not resolved yet. */
+	models: Dict[];
+}
+
+export interface ParsedFile {
+	providers: Map<string, PrivateProvider>;
+	defaults: PrivateDefaults;
+	issues: string[];
+}
+
+const FILE_KEYS = ["providers", "default"];
+
+const PROVIDER_KEYS = ["name", "baseUrl", "api", "apiKey", "authHeader", "headers", "compat", "models"];
+const PROVIDER_REJECTED: Dict = {
+	oauth: "oauth needs provider code, so it cannot come from a JSON file",
+	modelOverrides: "modelOverrides would change a model defined elsewhere",
+	inherit: "inherit belongs inside a models entry",
+};
+
+const DEFAULT_KEYS = ["name", "baseUrl", "apiKey", "api", "authHeader", "headers", "compat"];
+const DEFAULT_REJECTED: Dict = {
+	models: "default supplies values, not model definitions",
+	modelOverrides: "default supplies values, not model overrides",
+	oauth: "oauth needs provider code, so it cannot come from a JSON file",
+};
+
+const MODEL_KEYS = [
+	"id", "name", "api", "baseUrl", "reasoning", "thinkingLevelMap", "input", "inputLimits", "cost",
+	"promptCache", "contextWindow", "maxTokens", "samplingParams", "headers", "compat", "inherit",
+];
+
+// pi's compat vocabulary. A key pi adds later is unknown here, so only a near
+// miss is reported; anything else is left to pi.
+const COMPAT_KEYS = [
+	"supportsStore", "supportsDeveloperRole", "supportsReasoningEffort", "supportsUsageInStreaming", "supportsFinishReason",
+	"maxTokensField", "requiresToolResultName", "requiresAssistantAfterToolResult", "requiresThinkingAsText",
+	"requiresReasoningContentOnAssistantMessages", "thinkingFormat", "chatTemplateKwargs", "chatTemplateArgs",
+	"cacheControlFormat", "openRouterRouting", "vercelGatewayRouting", "supportsOpenAIGrammarTools", "supportsStrictMode",
+	"sendSessionAffinityHeaders", "sessionAffinityFormat", "supportsLongCacheRetention", "vllmPriority", "zaiToolStream",
+	"supportsMaxOutputTokens", "supportsEagerToolInputStreaming", "supportsCacheControlOnTools", "supportsTemperature",
+	"forceAdaptiveThinking", "allowEmptySignature", "supportsStrictTools", "supportsMidConvoEffort", "allowedFallbackModels",
+	"supportsMidConvoSystemMessages", "supportsMidConvoToolAdditions", "supportsMidConvoToolChanges",
+];
+
+export function parsePrivateFile(file: Dict | undefined): ParsedFile {
+	const issues: string[] = [];
+	const providers = new Map<string, PrivateProvider>();
+	const defaults = noDefaults();
+	if (!file) return { providers, defaults, issues };
+
+	for (const key of Object.keys(file)) {
+		if (FILE_KEYS.includes(key)) continue;
+		const hint = suggest(key, FILE_KEYS);
+		issues.push(`"${key}" is not supported${hint ? `; did you mean "${hint}"` : ""} (valid: ${FILE_KEYS.join(", ")})`);
+	}
+
+	readDefaults(file.default, defaults, issues);
+
+	if (file.providers !== undefined && !isObj(file.providers)) {
+		issues.push('"providers" must be an object.');
+		return { providers, defaults, issues };
+	}
+	for (const [providerId, entry] of Object.entries((file.providers as Dict | undefined) ?? {})) {
+		const parsed = parseProvider(providerId, entry, issues);
+		if (parsed) providers.set(providerId, parsed);
+	}
+	return { providers, defaults, issues };
+}
+
+function parseProvider(providerId: string, entry: unknown, issues: string[]): PrivateProvider | undefined {
+	const where = `providers["${providerId}"]`;
+	if (providerId === "") {
+		issues.push("a provider id must not be empty.");
+		return undefined;
+	}
+	if (!isObj(entry)) {
+		issues.push(`${where} must be an object.`);
+		return undefined;
+	}
+	const config: Dict = {};
+	const models: Dict[] = [];
+	for (const [key, value] of Object.entries(entry)) {
+		if (key === "models") {
+			if (!Array.isArray(value)) issues.push(`${where}.models must be an array.`);
+			else value.forEach((model, index) => {
+				const parsed = parseModel(`${where}.models[${index}]`, model, issues);
+				if (parsed) models.push(parsed);
+			});
+			continue;
+		}
+		if (key in PROVIDER_REJECTED) {
+			issues.push(`${where}.${key} is ignored: ${PROVIDER_REJECTED[key]}.`);
+			continue;
+		}
+		if (!PROVIDER_KEYS.includes(key)) {
+			const hint = suggest(key, PROVIDER_KEYS);
+			issues.push(`${where}.${key} is ignored${hint ? `; did you mean "${hint}"` : ""} (valid: ${PROVIDER_KEYS.join(", ")})`);
+			continue;
+		}
+		config[key] = value;
+	}
+	for (const key of ["name", "baseUrl", "api", "apiKey"]) {
+		if (config[key] !== undefined && (typeof config[key] !== "string" || config[key] === "")) issues.push(`${where}.${key} must be a non-empty string.`);
+	}
+	if (config.authHeader !== undefined && typeof config.authHeader !== "boolean") issues.push(`${where}.authHeader must be a boolean.`);
+	if (config.headers !== undefined) checkHeaders(`${where}.headers`, config.headers, issues);
+	if (config.compat !== undefined) checkCompat(`${where}.compat`, config.compat, issues);
+	if (models.length === 0) issues.push(`${where} is ignored: a private provider must define its "models".`);
+	return models.length > 0 ? { config, models } : undefined;
+}
+
+function parseModel(where: string, entry: unknown, issues: string[]): Dict | undefined {
+	if (!isObj(entry)) {
+		issues.push(`${where} must be an object.`);
+		return undefined;
+	}
+	for (const key of Object.keys(entry)) {
+		if (MODEL_KEYS.includes(key)) continue;
+		const hint = suggest(key, MODEL_KEYS);
+		issues.push(`${where}.${key} is ignored${hint ? `; did you mean "${hint}"` : ""} (valid: ${MODEL_KEYS.join(", ")})`);
+	}
+	if (typeof entry.id !== "string" || entry.id === "") {
+		issues.push(`${where}.id must be a non-empty string.`);
+		return undefined;
+	}
+	if (entry.inherit !== undefined && (typeof entry.inherit !== "string" || entry.inherit === "")) {
+		issues.push(`${where}.inherit must be a string like "provider/modelId".`);
+	}
+	for (const key of ["name", "api", "baseUrl"]) {
+		if (entry[key] !== undefined && typeof entry[key] !== "string") issues.push(`${where}.${key} must be a string.`);
+	}
+	if (entry.reasoning !== undefined && typeof entry.reasoning !== "boolean") issues.push(`${where}.reasoning must be a boolean.`);
+	if (entry.input !== undefined && (!Array.isArray(entry.input) || entry.input.some((kind) => kind !== "text" && kind !== "image"))) {
+		issues.push(`${where}.input must be an array of "text" and "image".`);
+	}
+	for (const key of ["contextWindow", "maxTokens"]) {
+		if (entry[key] !== undefined && (typeof entry[key] !== "number" || entry[key] <= 0)) issues.push(`${where}.${key} must be a positive number.`);
+	}
+	if (entry.cost !== undefined && !isObj(entry.cost)) issues.push(`${where}.cost must be an object.`);
+	if (entry.headers !== undefined) checkHeaders(`${where}.headers`, entry.headers, issues);
+	if (entry.compat !== undefined) checkCompat(`${where}.compat`, entry.compat, issues);
+	return entry;
+}
+
+function readDefaults(block: unknown, out: PrivateDefaults, issues: string[]): void {
+	if (block === undefined) return;
+	if (!isObj(block)) {
+		issues.push('"default" must be an object.');
+		return;
+	}
+	for (const key of Object.keys(block)) if (key !== "providers") issues.push(`"default.${key}" is not supported; only "providers" is.`);
+	if (block.providers !== undefined && !isObj(block.providers)) {
+		issues.push('"default.providers" must be an object.');
+		return;
+	}
+	for (const [id, entry] of Object.entries((block.providers as Dict | undefined) ?? {})) {
+		const where = `default.providers["${id}"]`;
+		if (!isObj(entry)) {
+			issues.push(`${where} must be an object.`);
+			continue;
+		}
+		if (Object.keys(entry).length === 0) {
+			issues.push(`${where} is empty.`);
+			continue;
+		}
+		const layer: Dict = {};
+		for (const [key, value] of Object.entries(entry)) {
+			if (key in DEFAULT_REJECTED) {
+				issues.push(`${where}.${key} is ignored: ${DEFAULT_REJECTED[key]}.`);
+				continue;
+			}
+			if (!DEFAULT_KEYS.includes(key)) {
+				const hint = suggest(key, DEFAULT_KEYS);
+				issues.push(`${where}.${key} is ignored${hint ? `; did you mean "${hint}"` : ""} (valid: ${DEFAULT_KEYS.join(", ")})`);
+				continue;
+			}
+			layer[key] = value;
+		}
+		for (const key of ["name", "baseUrl", "apiKey", "api"]) {
+			if (layer[key] !== undefined && (typeof layer[key] !== "string" || layer[key] === "")) issues.push(`${where}.${key} must be a non-empty string.`);
+		}
+		if (layer.authHeader !== undefined && typeof layer.authHeader !== "boolean") issues.push(`${where}.authHeader must be a boolean.`);
+		if (layer.headers !== undefined) checkHeaders(`${where}.headers`, layer.headers, issues);
+		if (layer.compat !== undefined) checkCompat(`${where}.compat`, layer.compat, issues);
+		if (id === "*") out.star = layer;
+		else out.exact.set(id, layer);
+	}
+}
+
+function checkHeaders(where: string, value: unknown, issues: string[]): void {
+	if (!isObj(value) || Object.values(value).some((header) => typeof header !== "string")) issues.push(`${where} must map strings to strings.`);
+}
+
+function checkCompat(where: string, value: unknown, issues: string[]): void {
+	if (!isObj(value)) {
+		issues.push(`${where} must be an object.`);
+		return;
+	}
+	for (const key of Object.keys(value)) {
+		if (COMPAT_KEYS.includes(key)) continue;
+		const hint = suggest(key, COMPAT_KEYS);
+		if (hint) issues.push(`${where}.${key} is ignored; did you mean "${hint}"?`);
+	}
+}

package/extensions/private-models/resolve-inherit.ts

@@ -0,0 +1,146 @@
+/**
+ * `inherit` inside models.private.json, plus the model fields pi fills in for
+ * models.json entries but not for providers that an extension registers.
+ *
+ * `inherit` copies another model's configuration into an entry: everything
+ * except `id`, `provider` and `baseUrl`, and a value written on the entry itself
+ * always wins.
+ */
+import { isObj, type Dict } from "./utils/read-agent-json.ts";
+import { merge, omit } from "./utils/fields.ts";
+import { suggest } from "./utils/suggest.ts";
+import type { PrivateProvider } from "./private-file.ts";
+
+/** Fields an entry keeps for itself. */
+export const LOCAL_KEYS = ["id", "provider", "baseUrl", "inherit"];
+
+/** Where an inherited model's fields come from. */
+export interface Lookup {
+	/** Entry as written: the private file first, then models.json. */
+	entry(providerId: string, modelId: string): Dict | undefined;
+	/** Model pi composed, for targets that are not written in a file. */
+	model(providerId: string, modelId: string): Dict | undefined;
+	/** Model ids of a provider, for the did-you-mean hint. */
+	ids(providerId: string): string[];
+}
+
+export interface Plan {
+	/** providerId -> its models entries with `inherit` resolved. */
+	models: Map<string, Dict[]>;
+	issues: string[];
+	/** References with no target. Only a problem once pi is running: catalogs live there. */
+	unresolved: string[];
+}
+
+/** Providers in a models.json, used both as resolve targets and for provider ids. */
+export const fileProviders = (file: Dict | undefined): Dict => (isObj(file?.providers) ? file.providers : {});
+
+const entriesOf = (providers: Dict, providerId: string): Dict[] => {
+	const entry = providers[providerId];
+	return isObj(entry) && Array.isArray(entry.models) ? entry.models.filter(isObj) : [];
+};
+
+export function planInherit(providers: Map<string, PrivateProvider>, lookup: Lookup, knownProviders: ReadonlySet<string>): Plan {
+	const models = new Map<string, Dict[]>();
+	const issues: string[] = [];
+	const unresolved: string[] = [];
+
+	/** `"provider/modelId"`, or a model of this provider when the prefix is no provider. */
+	const splitRef = (ref: string, providerId: string): [string, string] => {
+		const slash = ref.indexOf("/");
+		return slash > 0 && knownProviders.has(ref.slice(0, slash)) ? [ref.slice(0, slash), ref.slice(slash + 1)] : [providerId, ref];
+	};
+
+	/** Closest existing reference, for the did-you-mean hint. */
+	const nearest = (providerId: string, modelId: string): string | undefined => {
+		const nearModel = suggest(modelId, lookup.ids(providerId));
+		if (nearModel) return `${providerId}/${nearModel}`;
+		const nearProvider = suggest(providerId, [...knownProviders]);
+		return nearProvider && nearProvider !== providerId ? `${nearProvider}/${modelId}` : undefined;
+	};
+
+	/** Fields a target contributes; "cycle" when following `inherit` loops back. */
+	const fieldsOf = (providerId: string, modelId: string, chain: string[]): Dict | "cycle" | undefined => {
+		const key = `${providerId}/${modelId}`;
+		if (chain.includes(key)) return "cycle";
+		const entry = lookup.entry(providerId, modelId);
+		const written = entry ?? lookup.model(providerId, modelId);
+		if (!written) return undefined;
+		const own = omit(written, LOCAL_KEYS);
+		const ref = entry?.inherit;
+		if (typeof ref !== "string" || ref === "") return own;
+		const [provider, model] = splitRef(ref, providerId);
+		const parent = fieldsOf(provider, model, [...chain, key]);
+		if (parent === "cycle" || parent === undefined) return parent;
+		return merge(parent, own);
+	};
+
+	for (const [providerId, provider] of providers) {
+		models.set(providerId, provider.models.map((entry) => {
+			const ref = entry.inherit;
+			if (typeof ref !== "string" || ref === "") return omit(entry, ["inherit"]);
+			const where = `providers["${providerId}"].models "${entry.id}"`;
+			const [provider, model] = splitRef(ref, providerId);
+			const inherited = fieldsOf(provider, model, []);
+			if (inherited === "cycle") {
+				issues.push(`${where}: inherit "${ref}" forms a cycle; ignored.`);
+				return omit(entry, ["inherit"]);
+			}
+			if (inherited === undefined) {
+				const near = nearest(provider, model);
+				unresolved.push(`${where}: inherit target "${ref}" was not found${near ? `; did you mean "${near}"?` : ""}`);
+				return omit(entry, ["inherit"]);
+			}
+			return merge(inherited, omit(entry, ["inherit"]));
+		}));
+	}
+	return { models, issues, unresolved };
+}
+
+/** Stage one: everything written in a file, no runtime yet. */
+export function fileLookup(providers: Map<string, PrivateProvider>, publicFile: Dict | undefined): Lookup {
+	const publicProviders = fileProviders(publicFile);
+	const entries = (providerId: string): Dict[] => [...(providers.get(providerId)?.models ?? []), ...entriesOf(publicProviders, providerId)];
+	return {
+		entry: (providerId, modelId) => entries(providerId).find((entry) => entry.id === modelId),
+		model: () => undefined,
+		ids: (providerId) => entries(providerId).map((entry) => entry.id),
+	};
+}
+
+/** Stage two: the private file first, then what pi composed. */
+export function storeLookup(providers: Map<string, PrivateProvider>, runtime: any): Lookup {
+	const composed = (providerId: string): Dict[] => {
+		try {
+			const models = runtime?.models?.getModels?.(providerId);
+			return Array.isArray(models) ? models : [];
+		} catch {
+			return [];
+		}
+	};
+	const ids = (providerId: string): string[] => [...(providers.get(providerId)?.models ?? []), ...composed(providerId)]
+		.map((entry) => entry?.id)
+		.filter((id): id is string => typeof id === "string");
+	return {
+		entry: (providerId, modelId) => providers.get(providerId)?.models.find((entry) => entry.id === modelId),
+		model: (providerId, modelId) => composed(providerId).find((model) => model?.id === modelId),
+		ids,
+	};
+}
+
+/** Fields pi fills in for models.json entries: a registered provider has to carry them itself. */
+export function withModelDefaults(entry: Dict): Dict {
+	const cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, ...(isObj(entry.cost) ? entry.cost : {}) };
+	return {
+		...entry,
+		name: typeof entry.name === "string" ? entry.name : entry.id,
+		reasoning: typeof entry.reasoning === "boolean" ? entry.reasoning : false,
+		input: Array.isArray(entry.input) ? entry.input : ["text"],
+		cost,
+		contextWindow: typeof entry.contextWindow === "number" ? entry.contextWindow : 128000,
+		maxTokens: typeof entry.maxTokens === "number" ? entry.maxTokens : 16384,
+	};
+}
+
+/** Provider ids known before pi starts: the private file, models.json, and what is handed in. */
+export const providerIdsOf = (file: Dict | undefined): string[] => Object.keys(fileProviders(file));

package/extensions/private-models/utils/fields.ts

@@ -0,0 +1,31 @@
+/**
+ * Field-level operations, following pi's own merge rules: object-valued fields
+ * merge key by key, everything else is replaced.
+ */
+import { isObj, type Dict } from "./read-agent-json.ts";
+
+const NESTED_KEYS = ["compat", "headers", "openRouterRouting", "vercelGatewayRouting", "chatTemplateKwargs", "chatTemplateArgs"];
+
+/** `override` wins per key; nested object fields merge one level deeper. */
+export function merge(base: Dict, override: Dict): Dict {
+	const merged: Dict = { ...base, ...override };
+	for (const key of NESTED_KEYS) {
+		if (isObj(base[key]) && isObj(override[key])) merged[key] = { ...base[key], ...override[key] };
+	}
+	return merged;
+}
+
+/** Subset of `source` holding only defined values for `keys`. */
+export function pick(source: Dict | undefined, keys: readonly string[]): Dict | undefined {
+	if (!source) return undefined;
+	const out: Dict = {};
+	for (const key of keys) if (source[key] !== undefined) out[key] = source[key];
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Copy of `source` without `keys`. Undefined values are dropped, so they never mask an inherited field. */
+export function omit(source: Dict, keys: readonly string[]): Dict {
+	const out: Dict = {};
+	for (const [key, value] of Object.entries(source)) if (value !== undefined && !keys.includes(key)) out[key] = value;
+	return out;
+}

package/extensions/private-models/utils/read-agent-json.ts

@@ -0,0 +1,34 @@
+/**
+ * Read the JSON files in pi's agent directory, and narrow unknown JSON values.
+ * Tolerates comments and trailing commas exactly like pi's own reader.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Dict = Record<string, any>;
+
+export const isObj = (value: unknown): value is Dict =>
+	typeof value === "object" && value !== null && !Array.isArray(value) && !Buffer.isBuffer(value);
+
+/** pi's agent directory (this package imports pi types only, so resolve it here). */
+export function agentDir(): string {
+	const dir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+	return dir.startsWith("~") ? join(homedir(), dir.slice(1)) : dir;
+}
+
+/** Parsed `<agentDir>/<name>`, or undefined when it is missing, unreadable or not an object. */
+export function readAgentJson(name: string): Dict | undefined {
+	try {
+		const text = readFileSync(join(agentDir(), name), "utf8").replace(/^\uFEFF/, "");
+		const parsed: unknown = JSON.parse(stripJsonComments(text));
+		return isObj(parsed) ? parsed : undefined;
+	} catch {
+		return undefined; // pi reports its own errors
+	}
+}
+
+const stripJsonComments = (input: string): string =>
+	input
+		.replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (m) => (m[0] === '"' ? m : ""))
+		.replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (m: string, tail: string) => tail ?? (m[0] === '"' ? m : ""));

package/extensions/private-models/utils/suggest.ts

@@ -0,0 +1,32 @@
+/**
+ * Near-miss matching for "did you mean" hints. Only clearly similar names count,
+ * so a key pi adds later never triggers a bogus suggestion.
+ */
+export function suggest(key: string, known: readonly string[]): string | undefined {
+	let best: string | undefined;
+	let score = Infinity;
+	for (const candidate of known) {
+		const d = distance(key.toLowerCase(), candidate.toLowerCase());
+		if (d < score) {
+			score = d;
+			best = candidate;
+		}
+	}
+	if (best === undefined) return undefined;
+	if (score <= 2) return best;
+	const a = key.toLowerCase();
+	const b = best.toLowerCase();
+	return a.length >= 6 && (b.startsWith(a) || a.startsWith(b)) ? best : undefined;
+}
+
+function distance(a: string, b: string): number {
+	let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+	for (let i = 1; i <= a.length; i++) {
+		const next = [i];
+		for (let j = 1; j <= b.length; j++) {
+			next[j] = Math.min(prev[j] + 1, next[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		}
+		prev = next;
+	}
+	return prev[b.length];
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pi-private-models",
+  "version": "0.1.0",
+  "description": "pi extension that keeps private model providers out of the published models.json",
+  "type": "module",
+  "license": "Apache-2.0",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/private-models/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --no-warnings --test tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ]
+}