@companion-ai/feynman 0.5.14 → 0.5.15

package/RELEASES.md

@@ -6,6 +6,14 @@ GitHub release notes are generated from the matching `## vX.Y.Z` section in this
 
 ## Unreleased
 
+## v0.5.15 - 2026-09-29
+
+- **Pi 0.99.1, pinned.** Feynman accepted any Pi version, so npm installs picked up Pi 0.99.1 the day it was released, untested, and Pi 0.99 warns on every launch about how Feynman declared it. Feynman now runs on Pi 0.99.1, which adds MCP server support (`/mcp`), declared the way Pi asks, and pinned so new Pi releases arrive only after they pass Feynman's checks. If npm has `legacy-peer-deps` on, it skips Pi; `feynman` now says to reinstall with `--legacy-peer-deps=false` instead of failing on a missing package.
+- **npm installs use a patched undici.** pi-subagents pins undici 8.10.0, which ten advisories published on 2026-09-29 affect (plus GHSA-3wwx-pv8p-q78v), and npm hoisted that copy for every package in an npm install. Feynman now depends on a patched undici directly, so only pi-subagents keeps 8.10.0 until it releases its bump (nicobailon/pi-subagents#2548); the standalone installers were already patched. Correction to the 0.5.14 notes: pi-subagents' background runner installs its undici as the process-wide fetch and WebSocket, so the advisories do apply to background subagent runs.
+- **`feynman model set` explains a model it cannot use.** "Model not available in Pi auth storage" gave no reason. It now says which applies: the provider has no credentials (with the `feynman model login` command to run), a local provider in `models.json` has no `apiKey` (Pi hides providers without one; a placeholder such as `"local"` is enough), or the ID is unknown (with close matches, for example `gpt-5.6` suggests `openai/gpt-5.6-terra`).
+- **Parallel OpenAlex semantic searches no longer fail.** OpenAlex allows one semantic search per second, and parallel searches got `429 Too Many Requests`: in a live test of six at once, five failed. They now run one after another at that pace, and a 429 that asks for a short wait is retried once. Six parallel searches now all succeed.
+- `feynman model set` with no model opens a picker of the available models instead of failing. `feynman model help` lists the model commands, an unknown model subcommand points to it, and `-h` works like `--help`.
+
 ## v0.5.14 - 2026-09-28
 
 - **The Windows installer no longer fails on slow networks (#309).** When usage telemetry could not reach PostHog quickly, the PostHog library printed a timeout to stderr, and Windows PowerShell treats stderr from the installer's `feynman --help` check as a failure. Each telemetry send now has a 1.5 s budget and ends quietly, so no command waits on telemetry (on a stalled network `feynman --help` took 11 s and printed two errors; it now takes about 2 s and prints nothing). The installers also run their checks with telemetry off and judge them by exit code.

package/bin/feynman.js

@@ -40,4 +40,15 @@ if (process.argv.length === 3 && process.argv[2] === "--version") {
   process.exit(0);
 }
 
+// Pi is a peer dependency, as Pi requires of extension packages, and npm skips
+// peers when legacy-peer-deps is on.
+try {
+  import.meta.resolve("@earendil-works/pi-coding-agent");
+  import.meta.resolve("@earendil-works/pi-ai");
+} catch {
+  console.error("feynman could not find its Pi runtime (@earendil-works/pi-coding-agent), which npm skips when legacy-peer-deps is on.");
+  console.error("Reinstall with: npm install -g @companion-ai/feynman --legacy-peer-deps=false");
+  process.exit(1);
+}
+
 await import(pathToFileURL(resolve(here, "..", "dist", "index.js")).href);

package/dist/cli.js

@@ -22,7 +22,7 @@ import { installPiPackage, listOptionalPackagePresets, normalizeOptionalPackageP
 import { canonicalizeModelSpec, ensureFeynmanSettings, normalizeThinkingLevel, readJson, } from "./pi/settings.js";
 import { BUNDLED_PI_PACKAGES, buildPiEnv } from "./pi/runtime.js";
 import { getConfiguredServiceTier, normalizeServiceTier, setConfiguredServiceTier } from "./model/service-tier.js";
-import { authenticateModelProvider, getCurrentModelSpec, isLocalModelProvider, loginModelProvider, logoutModelProvider, printModelList, setDefaultModelSpec, } from "./model/commands.js";
+import { authenticateModelProvider, getCurrentModelSpec, isLocalModelProvider, loginModelProvider, logoutModelProvider, printModelList, selectDefaultModel, setDefaultModelSpec, } from "./model/commands.js";
 import { buildModelStatusSnapshotFromRecords, getAuthenticatedModelRecords, isProClassModelSpec, getSupportedModelRecords, } from "./model/catalog.js";
 import { clearSearchConfig, printSearchStatus, setSearchProvider } from "./search/commands.js";
 import { fetchLatestFeynmanVersion, getFeynmanUpgradeLines, isNewerVersion } from "./system/self-update.js";
@@ -189,10 +189,15 @@ async function handleModelCommand(subcommand, args, feynmanSettingsPath, feynman
     }
     if (subcommand === "set") {
         const spec = args[0];
-        if (!spec) {
+        if (spec) {
+            await setDefaultModelSpec(feynmanSettingsPath, feynmanAuthPath, spec);
+        }
+        else if (process.stdin.isTTY && process.stdout.isTTY) {
+            await selectDefaultModel(feynmanSettingsPath, feynmanAuthPath);
+        }
+        else {
             throw new Error("Usage: feynman model set <provider/model|provider:model>");
         }
-        await setDefaultModelSpec(feynmanSettingsPath, feynmanAuthPath, spec);
         return;
     }
     if (subcommand === "tier") {
@@ -214,7 +219,14 @@ async function handleModelCommand(subcommand, args, feynmanSettingsPath, feynman
         console.log(`Service tier set to ${tier}`);
         return;
     }
-    throw new Error(`Unknown model command: ${subcommand}`);
+    if (subcommand === "help") {
+        printSection("Model Management");
+        for (const command of cliCommandSections.find((section) => section.title === "Model Management")?.commands ?? []) {
+            printHelpLine(command.usage, command.description);
+        }
+        return;
+    }
+    throw new Error(`Unknown model command: ${subcommand}\nRun \`feynman model help\` to see model commands.`);
 }
 async function handleUpdateCommand(piOptions, feynmanVersion, source) {
     const latestFeynmanVersionPromise = fetchLatestFeynmanVersion();
@@ -436,7 +448,7 @@ async function runMain(input) {
             doctor: { type: "boolean" },
             export: { type: "string" },
             fork: { type: "string" },
-            help: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
             version: { type: "boolean" },
             "alpha-login": { type: "boolean" },
             "alpha-logout": { type: "boolean" },
@@ -614,7 +626,7 @@ async function runMain(input) {
         const modelRuntime = await createModelRuntime(feynmanAuthPath);
         const canonicalModelSpec = canonicalizeModelSpec(requestedExplicitModelSpec, modelRuntime);
         if (!canonicalModelSpec) {
-            throw new Error(`Unknown model: ${requestedExplicitModelSpec}`);
+            throw new Error(`Unknown model: ${requestedExplicitModelSpec}. Run \`feynman model list\` to see available models.`);
         }
         explicitModelSpec = canonicalModelSpec;
     }

package/dist/model/commands.js

@@ -5,7 +5,7 @@ import { readJson } from "../pi/settings.js";
 import { promptChoice, promptSelect, promptText } from "../setup/prompts.js";
 import { openUrl } from "../system/open-url.js";
 import { printInfo, printSection, printSuccess, printWarning } from "../ui/terminal.js";
-import { buildModelStatusSnapshotFromRecords, chooseRecommendedModel, getAuthenticatedModelRecords, getAvailableModelRecords, getSupportedModelRecords, } from "./catalog.js";
+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";
@@ -821,10 +821,32 @@ export async function logoutModelProvider(authPath, providerId) {
     await modelRuntime.logout(provider.id);
     printSuccess(`Model provider logout complete: ${provider.id}`);
 }
+// Explains why `feynman model set <spec>` found no usable model.
+async function describeUnavailableModelSpec(authPath, spec) {
+    const input = spec.trim().replace(/^([^/:]+):(.+)$/, "$1/$2").toLowerCase();
+    const known = (await getSupportedModelRecords(authPath)).find((model) => `${model.provider}/${model.id}`.toLowerCase() === input || model.id.toLowerCase() === input);
+    if (known) {
+        const knownSpec = `${known.provider}/${known.id}`;
+        if (isProClassModelSpec(knownSpec)) {
+            return `Pro-class model disabled: ${knownSpec}. Choose an approved research model.`;
+        }
+        if (isLocalModelProvider(authPath, known.provider)) {
+            return `${knownSpec} has no API key. Pi only lists a local provider when it has one: add "apiKey": "local" to the ${known.provider} provider in ${getModelsJsonPath(authPath)}.`;
+        }
+        return `${knownSpec} has no credentials. Run \`feynman model login ${known.provider}\` first.`;
+    }
+    const modelId = input.slice(input.lastIndexOf("/") + 1);
+    const matches = (await getAvailableModelRecords(authPath))
+        .map((model) => `${model.provider}/${model.id}`)
+        .filter((candidate) => candidate.toLowerCase().includes(modelId))
+        .slice(0, 5);
+    const suggestion = matches.length > 0 ? ` Did you mean ${matches.join(", ")}?` : "";
+    return `Unknown model: ${spec}.${suggestion} Run \`feynman model list\` to see available models.`;
+}
 export async function setDefaultModelSpec(settingsPath, authPath, spec) {
     const resolvedSpec = await resolveAvailableModelSpec(authPath, spec);
     if (!resolvedSpec) {
-        throw new Error(`Model not available in Pi auth storage: ${spec}. Run \`feynman model list\` first.`);
+        throw new Error(await describeUnavailableModelSpec(authPath, spec));
     }
     const [provider, ...rest] = resolvedSpec.split("/");
     const modelId = rest.join("/");
@@ -834,6 +856,22 @@ export async function setDefaultModelSpec(settingsPath, authPath, spec) {
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
     printSuccess(`Research default model set to ${resolvedSpec}`);
 }
+export async function selectDefaultModel(settingsPath, authPath) {
+    const status = await collectModelStatus(settingsPath, authPath);
+    if (status.availableModels.length === 0) {
+        printWarning("No authenticated Pi models are currently available.");
+        for (const line of status.guidance) {
+            printInfo(line);
+        }
+        return;
+    }
+    const spec = await promptSelect("Choose the default research model:", status.availableModels.map((value) => ({
+        value,
+        label: value,
+        hint: value === status.current ? "current" : value === status.recommended ? "recommended" : undefined,
+    })), status.current ?? status.recommended);
+    await setDefaultModelSpec(settingsPath, authPath, spec);
+}
 export async function runModelSetup(settingsPath, authPath) {
     let status = await collectModelStatus(settingsPath, authPath);
     while (status.availableModels.length === 0) {

package/extensions/research-tools/request-pacer.ts

@@ -0,0 +1,17 @@
+// Runs requests one after another, each starting at least `minGapMs` after the
+// previous one started. Pi runs parallel tool calls in one process, so this keeps
+// them under a service's per-second limit.
+export function createRequestPacer(): <T>(minGapMs: number, run: () => Promise<T>) => Promise<T> {
+	let queue: Promise<unknown> = Promise.resolve();
+	let lastStartedAt = Number.NEGATIVE_INFINITY;
+	return <T>(minGapMs: number, run: () => Promise<T>): Promise<T> => {
+		const next = queue.then(async () => {
+			const wait = lastStartedAt + minGapMs - Date.now();
+			if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+			lastStartedAt = Date.now();
+			return run();
+		});
+		queue = next.catch(() => {});
+		return next;
+	};
+}

package/extensions/research-tools/science-database-openalex.ts

@@ -1,4 +1,5 @@
 import { OPENALEX_API_KEY_HINT, openAlexRequestFailure, searchExactOpenAlex } from "./science-database-openalex-exact.js";
+import { createRequestPacer } from "./request-pacer.js";
 
 export type OpenAlexScienceDatabaseSource = "openalex";
 
@@ -96,9 +97,18 @@ function scrubOpenAlexText(text: string, url: URL): string {
 	return scrubbed;
 }
 
-async function fetchJson(url: URL): Promise<{ credentialStatus: string; endpoint: string; payload: unknown; usingApiKey: boolean }> {
-	const auth = addAuth(url);
-	const endpoint = scrubOpenAlexEndpoint(url);
+type OpenAlexResponse =
+	| { ok: true; payload: unknown }
+	| { ok: false; status: number; statusText: string; retryAfterMs?: number; body: string };
+
+// Semantic search allows one request per second (429 with Retry-After: 1), so
+// semantic requests are paced. A 429 that asks for a short wait, such as one
+// caused by a subagent in another process, is retried once.
+const semanticPacer = createRequestPacer();
+const SEMANTIC_MIN_GAP_MS = 1100;
+const MAX_RETRY_WAIT_MS = 5000;
+
+async function requestOnce(url: URL): Promise<OpenAlexResponse> {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
 	try {
@@ -109,16 +119,39 @@ async function fetchJson(url: URL): Promise<{ credentialStatus: string; endpoint
 			},
 			signal: controller.signal,
 		});
-		if (!response.ok) {
-			const snippet = scrubOpenAlexText((await response.text()).slice(0, 4096), url).slice(0, 240);
-			throw openAlexRequestFailure(response.status, response.statusText, snippet, auth.usingApiKey);
-		}
-		return { ...auth, endpoint, payload: await response.json() };
+		if (response.ok) return { ok: true, payload: await response.json() };
+		const retryAfter = response.headers.get("retry-after");
+		const retryAfterSeconds = retryAfter === null ? Number.NaN : Number(retryAfter);
+		return {
+			ok: false,
+			status: response.status,
+			statusText: response.statusText,
+			retryAfterMs: Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0 ? retryAfterSeconds * 1000 : undefined,
+			body: (await response.text()).slice(0, 4096),
+		};
 	} finally {
 		clearTimeout(timeout);
 	}
 }
 
+async function fetchJson(url: URL): Promise<{ credentialStatus: string; endpoint: string; payload: unknown; usingApiKey: boolean }> {
+	const auth = addAuth(url);
+	const endpoint = scrubOpenAlexEndpoint(url);
+	const request = () =>
+		url.searchParams.has("search.semantic") ? semanticPacer(SEMANTIC_MIN_GAP_MS, () => requestOnce(url)) : requestOnce(url);
+	let response = await request();
+	if (!response.ok && response.status === 429 && response.retryAfterMs !== undefined && response.retryAfterMs <= MAX_RETRY_WAIT_MS) {
+		const waitMs = response.retryAfterMs + Math.random() * 500;
+		await new Promise((resolve) => setTimeout(resolve, waitMs));
+		response = await request();
+	}
+	if (!response.ok) {
+		const snippet = scrubOpenAlexText(response.body, url).slice(0, 240);
+		throw openAlexRequestFailure(response.status, response.statusText, snippet, auth.usingApiKey);
+	}
+	return { ...auth, endpoint, payload: response.payload };
+}
+
 function shortOpenAlexId(value: unknown): string | undefined {
 	const raw = stringValue(value);
 	if (!raw) return undefined;

package/extensions/research-tools/science-databases.ts

@@ -5,6 +5,7 @@ import { searchOpenAlex } from "./science-database-openalex.js";
 import { searchPreprints } from "./science-database-preprints.js";
 import { searchPubMed } from "./science-database-pubmed.js";
 import { isEuropePmcFullTextQuery, searchEuropePmcFullText } from "./science-database-europepmc-fulltext.js";
+import { createRequestPacer } from "./request-pacer.js";
 
 type ScienceDatabaseSource = "arxiv" | "biorxiv" | "crossref" | "europepmc" | "medrxiv" | "openalex" | "pubmed" | "semanticscholar";
 
@@ -141,21 +142,12 @@ function crossrefAuthors(value: unknown): string[] {
 // (x-concurrency-limit: 1); the polite pool, used when a mailto is sent, allows
 // three per second. Parallel DOI checks got 429 on most calls, so run Crossref
 // requests one after another at the pool's pace.
-let crossrefQueue: Promise<unknown> = Promise.resolve();
-let crossrefLastStartedAt = Number.NEGATIVE_INFINITY;
+const crossrefPacer = createRequestPacer();
 
 export function withCrossrefPacing<T>(polite: boolean, run: () => Promise<T>): Promise<T> {
 	// A little over the pool's limit: network jitter can land two requests paced
 	// exactly one second apart inside the same window.
-	const minGapMs = polite ? 400 : 1200;
-	const next = crossrefQueue.then(async () => {
-		const wait = crossrefLastStartedAt + minGapMs - Date.now();
-		if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
-		crossrefLastStartedAt = Date.now();
-		return run();
-	});
-	crossrefQueue = next.catch(() => {});
-	return next;
+	return crossrefPacer(polite ? 400 : 1200, run);
 }
 
 async function searchCrossref(params: ScienceDatabaseSearchParams): Promise<Record<string, unknown>> {

package/metadata/commands.mjs

@@ -115,7 +115,7 @@ export const cliCommandSections = [
 			{ usage: "feynman model list", description: "List available models in Pi auth storage." },
 			{ usage: "feynman model login [id]", description: "Authenticate a model provider with OAuth or API-key setup." },
 			{ usage: "feynman model logout [id]", description: "Clear stored auth for a model provider." },
-			{ usage: "feynman model set <provider/model>", description: "Set the default approved research model (also accepts provider:model)." },
+			{ usage: "feynman model set [provider/model]", description: "Set the default approved research model (also accepts provider:model); without one, pick from a list." },
 			{ usage: "feynman model tier [value]", description: "View or set the request service tier override." },
 		],
 	},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.5.14",
+  "version": "0.5.15",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",
@@ -79,18 +79,17 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@companion-ai/alpha-hub": "0.1.6",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
     "fast-xml-parser": "5.11.1",
     "pi-btw": "0.6.1",
     "pi-docparser": "4.0.0",
     "pi-subagents": "0.73.1",
     "pi-web-access": "0.33.0",
-    "posthog-node": "^5.53.0"
+    "posthog-node": "^5.53.0",
+    "undici": "^8.11.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-coding-agent": "0.99.1",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
@@ -117,6 +116,6 @@
     "access": "public"
   },
   "overrides": {
-    "undici": "^8.10.2"
+    "undici": "$undici"
   }
 }