@companion-ai/feynman 0.5.19 → 0.5.21

package/RELEASES.md

@@ -6,6 +6,14 @@ GitHub release notes are generated from the matching `## vX.Y.Z` section in this
 
 ## Unreleased
 
+## v0.5.21 - 2026-10-01
+
+- **LiteLLM and custom providers that read their key from an environment variable work again.** Since Pi 0.99, `models.json` resolves an environment variable only when written as `$NAME`; a bare name is sent as the key itself. Feynman's LiteLLM setup wrote `LITELLM_MASTER_KEY`, so requests went out as `Authorization: Bearer LITELLM_MASTER_KEY` and the proxy rejected them, and custom providers set up with a variable name broke the same way. Feynman now writes `$NAME`, and on start rewrites any `apiKey` in `models.json` that is a bare all-caps variable name, such as `LITELLM_MASTER_KEY`, to `$LITELLM_MASTER_KEY`. Literal keys, placeholders such as `local`, and `!command` values are left alone.
+
+## v0.5.20 - 2026-10-01
+
+- **Settings saved by Windows Notepad or PowerShell no longer stop Feynman.** Both can save UTF-8 with a byte-order mark, which JSON parsing rejects, so Feynman refused to start with "Invalid Feynman settings ... expected a JSON object", and other commands read the file as empty. Feynman now ignores the mark in `settings.json`, `auth.json`, and `web-search.json`, as Pi does. A settings file with a real JSON error now names the error, for example a trailing comma, instead of the generic message.
+
 ## v0.5.19 - 2026-10-01
 
 - **Word drafts open without LibreOffice.** `document_parse` needs LibreOffice for `.docx` files, which most machines lack, so reviewing a thesis or draft in Word format failed. When LibreOffice is missing, Feynman now reads the document's paragraph text directly from the `.docx` and says so; install LibreOffice for page layout, tables, footnotes, and images.

package/dist/config/json-file.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+// Windows Notepad and PowerShell 5.1 save UTF-8 with a byte-order mark, which
+// JSON.parse rejects. Pi strips it when it reads the same files.
+export function parseJsonText(source) {
+    return JSON.parse(source.replace(/^/, ""));
+}
+export function readJsonFile(path) {
+    return parseJsonText(readFileSync(path, "utf8"));
+}

package/dist/model/catalog.js

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
 import { getEnvApiKey } from "@earendil-works/pi-ai/compat";
+import { readJsonFile } from "../config/json-file.js";
 import { createModelRuntime } from "./registry.js";
 const PRO_CLASS_MODEL_PATTERN = /(?:^|[-_.:/])pro(?:$|[-_.:/])/i;
 // Pi catalogs these exact DeepSeek V4 Pro model IDs as ordinary open-weight
@@ -334,7 +334,7 @@ export async function getSupportedModelRecords(authPath) {
 function readExpiredOAuthProviders(authPath) {
     const expired = new Set();
     try {
-        const parsed = JSON.parse(readFileSync(authPath, "utf8"));
+        const parsed = readJsonFile(authPath);
         for (const [provider, credential] of Object.entries(parsed)) {
             if (!credential || typeof credential !== "object")
                 continue;

package/dist/model/commands.js

@@ -10,7 +10,7 @@ import { printInfo, printSection, printSuccess, printWarning } from "../ui/termi
 import { buildModelStatusSnapshotFromRecords, chooseRecommendedModel, getAuthenticatedModelRecords, getAvailableModelRecords, getSupportedModelRecords, isProClassModelSpec, } from "./catalog.js";
 import { MODEL_API_KEY_PROVIDERS } from "./api-key-providers.js";
 import { createModelRegistry, createModelRuntime, getModelsJsonPath } from "./registry.js";
-import { upsertProviderBaseUrl, upsertProviderConfig } from "./models-json.js";
+import { apiKeyReference, upsertProviderBaseUrl, upsertProviderConfig } from "./models-json.js";
 const exec = promisify(execCallback);
 async function collectModelStatus(settingsPath, authPath) {
     return buildModelStatusSnapshotFromRecords(await getSupportedModelRecords(authPath), await getAuthenticatedModelRecords(authPath), getCurrentModelSpec(settingsPath));
@@ -161,7 +161,7 @@ async function resolveApiKeyConfig(apiKeyConfig) {
             return undefined;
         }
     }
-    const envValue = process.env[trimmed];
+    const envValue = process.env[trimmed.replace(/^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/, "$1")];
     if (typeof envValue === "string" && envValue.trim()) {
         return envValue.trim();
     }
@@ -267,10 +267,10 @@ async function promptCustomProviderSetup() {
     }
     printInfo("API key value supports:");
     printInfo("  - literal secret (stored in models.json)");
-    printInfo("  - env var name (resolved at runtime)");
+    printInfo("  - env var name such as MY_API_KEY or $MY_API_KEY (resolved at runtime)");
     printInfo("  - !command (executes and uses stdout)");
     const apiKeyConfigRaw = (await promptText("API key / resolver", "")).trim();
-    const apiKeyConfig = apiKeyConfigRaw || "local";
+    const apiKeyConfig = apiKeyReference(apiKeyConfigRaw) || "local";
     if (!apiKeyConfigRaw) {
         printInfo("Using placeholder apiKey value (required by Pi for custom providers).");
     }
@@ -346,7 +346,7 @@ async function promptLiteLlmProviderSetup() {
         return undefined;
     }
     const hasKey = keySelection === 0;
-    const apiKeyConfig = hasKey ? "LITELLM_MASTER_KEY" : "local";
+    const apiKeyConfig = hasKey ? "$LITELLM_MASTER_KEY" : "local";
     const authHeader = hasKey;
     if (hasKey) {
         printInfo("Set LITELLM_MASTER_KEY in your shell or .env before using Feynman.");

package/dist/model/models-json.js

@@ -63,7 +63,9 @@ export function upsertProviderConfig(modelsJsonPath, providerId, patch) {
     if (patch.models !== undefined)
         nextProvider.models = patch.models;
     providers[providerId] = nextProvider;
-    const next = { ...value, providers };
+    return writeModelsJson(modelsJsonPath, { ...value, providers });
+}
+function writeModelsJson(modelsJsonPath, next) {
     try {
         mkdirSync(dirname(modelsJsonPath), { recursive: true });
         writeFileSync(modelsJsonPath, JSON.stringify(next, null, 2) + "\n", "utf8");
@@ -80,3 +82,31 @@ export function upsertProviderConfig(modelsJsonPath, providerId, patch) {
         return { ok: false, error: `Failed to write models.json: ${error instanceof Error ? error.message : String(error)}` };
     }
 }
+// Pi resolves an environment variable in `apiKey` only as $NAME or ${NAME}; a
+// bare name such as LITELLM_MASTER_KEY is sent as the key itself.
+const BARE_ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+export function apiKeyReference(value) {
+    return BARE_ENV_NAME.test(value) ? `$${value}` : value;
+}
+// Feynman's setup wrote bare names before Pi 0.99 stopped resolving them, so a
+// LiteLLM or custom provider sent "LITELLM_MASTER_KEY" as its key. Returns the
+// providers it rewrote to $NAME.
+export function migrateBareEnvApiKeys(modelsJsonPath) {
+    if (!existsSync(modelsJsonPath))
+        return [];
+    const read = readModelsJson(modelsJsonPath);
+    if (!read.ok)
+        return [];
+    const providers = { ...(read.value.providers ?? {}) };
+    const migrated = Object.keys(providers).filter((id) => {
+        const apiKey = providers[id]?.apiKey;
+        return typeof apiKey === "string" && BARE_ENV_NAME.test(apiKey);
+    });
+    if (migrated.length === 0)
+        return [];
+    for (const id of migrated) {
+        const provider = providers[id];
+        providers[id] = { ...provider, apiKey: apiKeyReference(provider.apiKey) };
+    }
+    return writeModelsJson(modelsJsonPath, { ...read.value, providers }).ok ? migrated : [];
+}

package/dist/model/service-tier.js

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { readJsonFile } from "../config/json-file.js";
 export const FEYNMAN_SERVICE_TIERS = [
     "auto",
     "default",
@@ -12,7 +13,7 @@ const OPENAI_SERVICE_TIERS = new Set(["auto", "default", "flex", "priority"]);
 const ANTHROPIC_SERVICE_TIERS = new Set(["auto", "standard_only"]);
 function readSettings(settingsPath) {
     try {
-        return JSON.parse(readFileSync(settingsPath, "utf8"));
+        return readJsonFile(settingsPath);
     }
     catch {
         return {};

package/dist/pi/settings.js

@@ -1,7 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { parseJsonText, readJsonFile } from "../config/json-file.js";
 import { BUNDLED_PI_PACKAGES, getFeynmanPackageSources, resolvePackageRoot } from "./runtime.js";
 import { choosePreferredModelRecord, getAvailableModelRecords } from "../model/catalog.js";
+import { migrateBareEnvApiKeys } from "../model/models-json.js";
+import { getModelsJsonPath } from "../model/registry.js";
 // Written by Feynman <= 0.4.0 next to a subagent extension path it managed.
 const LEGACY_RESEARCHER_EXTENSION_MARKER = "_feynmanResearchToolsExtension";
 function findModel(modelLookup, provider, id) {
@@ -50,7 +53,7 @@ export function readJson(path) {
         return {};
     }
     try {
-        return JSON.parse(readFileSync(path, "utf8"));
+        return readJsonFile(path);
     }
     catch (error) {
         if (process.env.FEYNMAN_DEBUG === "1") {
@@ -66,10 +69,11 @@ function readConfigObject(path, label) {
     const source = readFileSync(path, "utf8");
     let value;
     try {
-        value = JSON.parse(source);
+        value = parseJsonText(source);
     }
-    catch {
-        throw new Error(`Invalid ${label} at ${path}: expected a JSON object. The file was not changed.`);
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${label} at ${path}: ${reason}. Fix the JSON or delete the file. The file was not changed.`);
     }
     if (!isRecord(value)) {
         throw new Error(`Invalid ${label} at ${path}: expected a JSON object. The file was not changed.`);
@@ -178,6 +182,7 @@ export async function ensureFeynmanSettings(settingsPath, bundledSettingsPath, a
     const existing = existsSync(settingsPath) ? readConfigObject(settingsPath, "Feynman settings") : undefined;
     const settings = existing ? { ...existing.value } : {};
     const defaults = readConfigObject(bundledSettingsPath, "bundled Feynman settings").value;
+    migrateBareEnvApiKeys(getModelsJsonPath(authPath));
     for (const [key, value] of Object.entries({ ...defaults, defaultThinkingLevel })) {
         if (settings[key] === undefined)
             settings[key] = value;

package/dist/pi/web-access.js

@@ -1,5 +1,6 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { readJsonFile } from "../config/json-file.js";
 import { getFeynmanAgentDir, getFeynmanHome } from "../config/paths.js";
 // pi-web-access reads web-search.json from PI_CODING_AGENT_DIR.
 export function getPiWebSearchConfigPath(home) {
@@ -20,7 +21,7 @@ export function loadPiWebAccessConfig(configPath = getPiWebSearchConfigPath()) {
         return {};
     }
     try {
-        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        const parsed = readJsonFile(configPath);
         return parsed && typeof parsed === "object" ? parsed : {};
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",