@companion-ai/feynman 0.2.59 → 0.2.61

package/RELEASES.md

@@ -4,6 +4,34 @@ This file is the public release history for Feynman. Keep entries user-facing: w
 
 GitHub release notes are generated from the matching `## vX.Y.Z` section in this file.
 
+## v0.2.61 - 2026-06-11
+
+### Windows
+
+- Fixed bundled-package setup failing on every launch (#177, #170). Two root causes found by running the published package on real Windows runners: GNU tar (Git for Windows) treats the workspace archive's absolute `C:\...` path as a remote host spec ("Cannot connect ... resolve failed"), and the npm fallback spawned bare `npm` without a shell, which Windows rejects with EINVAL. The archive now extracts with relative paths, and npm is invoked through `npm-cli.js` with the running Node executable.
+
+### Runtime Reliability
+
+- The bundled workspace's alpha-hub copy now receives the same launch-time patches as the package-local copy, so the #167 search fix applies regardless of which copy resolves.
+
+### Validation
+
+- The multi-OS end-to-end workflow now verifies install, update, patch application, and live model + subagent smokes on Windows, Linux, and macOS at Node 24 and 25.
+
+## v0.2.60 - 2026-06-11
+
+### Node Support
+
+- Feynman now supports Node.js 25 (#177). The full test suite and live CLI flows (launch, update, alpha search, parallel web search) were validated on Node 20, 24, and 25; the supported range is now 20.19.0 through 25.x.
+
+### Runtime Reliability
+
+- Fixed the cryptic `Cannot convert argument to a ByteString because the character at index N has a value of M` crash (#171). It fires when a custom provider in `models.json` has a header value or API key containing characters above U+00FF (e.g. Chinese text) — HTTP headers cannot carry them. Feynman now reports exactly which provider and header is at fault and how to fix it, instead of an unattributed undici error.
+
+### Validation
+
+- Added a multi-OS end-to-end install workflow that exercises the published package on Windows, Linux, and macOS runners (Node 24 and 25): global install, version/update/package flows, launch-time patch assertions for the subagent spawn (#172) and structured search parser (#167) fixes, plus live model and subagent smokes.
+
 ## v0.2.59 - 2026-06-11
 
 ### Research Tools

package/bin/feynman.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 const MIN_NODE_VERSION = "20.19.0";
-const MAX_NODE_MAJOR = 24;
+const MAX_NODE_MAJOR = 25;
 const PREFERRED_NODE_MAJOR = 24;
 
 function parseNodeVersion(version) {

package/dist/pi/package-ops.js

@@ -3,7 +3,9 @@ import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, re
 import { fileURLToPath } from "node:url";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { resolveAdjacentNpmCommand } from "../../scripts/lib/npm-command.mjs";
 import { NATIVE_PACKAGE_SOURCES, supportsNativePackageSources } from "./package-presets.js";
+export { resolveAdjacentNpmCommand };
 import { applyFeynmanPackageManagerEnv, getFeynmanNpmPrefixPath } from "./runtime.js";
 import { getPathWithCurrentNode, resolveExecutable } from "../system/executables.js";
 const FILTERED_INSTALL_OUTPUT_PATTERNS = [
@@ -160,19 +162,6 @@ function ensureProjectInstallRoot(workingDir) {
     }
     return installRoot;
 }
-export function resolveAdjacentNpmCommand(nodeExecutablePath = process.execPath, platform = process.platform) {
-    const executableDir = dirname(nodeExecutablePath);
-    if (platform === "win32") {
-        const npmCliPath = resolve(executableDir, "node_modules", "npm", "bin", "npm-cli.js");
-        if (existsSync(npmCliPath)) {
-            return { command: nodeExecutablePath, args: [npmCliPath] };
-        }
-        const npmCmdPath = resolve(executableDir, "npm.cmd");
-        return existsSync(npmCmdPath) ? { command: npmCmdPath, args: [], shell: true } : undefined;
-    }
-    const candidate = resolve(executableDir, "npm");
-    return existsSync(candidate) ? { command: candidate, args: [] } : undefined;
-}
 function resolvePackageManagerCommand(settingsManager) {
     const configured = settingsManager.getNpmCommand();
     if (!configured || configured.length === 0) {

package/dist/pi/runtime-patches.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { patchAlphaHubAuthSource } from "../../scripts/lib/alpha-hub-auth-patch.mjs";
 import { patchAlphaHubSearchResultsSource, patchAlphaHubSearchSource } from "../../scripts/lib/alpha-hub-search-patch.mjs";
 import { patchPiAgentCoreSource } from "../../scripts/lib/pi-agent-core-patch.mjs";
+import { patchPiModelRegistrySource } from "../../scripts/lib/pi-model-registry-patch.mjs";
 import { patchPiPackageManagerSource } from "../../scripts/lib/pi-package-manager-patch.mjs";
 import { PI_SUBAGENTS_PATCH_TARGETS, patchPiSubagentsSource } from "../../scripts/lib/pi-subagents-patch.mjs";
 import { patchPiEditorSource, patchPiInteractiveThemeSource, patchPiTuiSource } from "../../scripts/lib/pi-tui-patch.mjs";
@@ -45,6 +46,7 @@ export function patchPiRuntimeNodeModules(appRoot) {
         changed = patchScopedPiPackageFileIfPresent(nodeModulesPath, "pi-tui", "dist/components/editor.js", patchPiEditorSource) || changed;
         changed = patchScopedPiPackageFileIfPresent(nodeModulesPath, "pi-coding-agent", "dist/modes/interactive/theme/theme.js", patchPiInteractiveThemeSource) || changed;
         changed = patchScopedPiPackageFileIfPresent(nodeModulesPath, "pi-coding-agent", "dist/core/package-manager.js", patchPiPackageManagerSource) || changed;
+        changed = patchScopedPiPackageFileIfPresent(nodeModulesPath, "pi-coding-agent", "dist/core/model-registry.js", patchPiModelRegistrySource) || changed;
         changed = patchFileIfPresent(resolve(nodeModulesPath, "@companion-ai", "alpha-hub", "src", "lib", "auth.js"), patchAlphaHubAuthSource) || changed;
         changed = patchFileIfPresent(resolve(nodeModulesPath, "@companion-ai", "alpha-hub", "src", "lib", "alphaxiv.js"), patchAlphaHubSearchSource) || changed;
         changed = patchFileIfPresent(resolve(nodeModulesPath, "@companion-ai", "alpha-hub", "src", "lib", "index.js"), patchAlphaHubSearchResultsSource) || changed;

package/dist/system/node-version.js

@@ -1,5 +1,5 @@
 export const MIN_NODE_VERSION = "20.19.0";
-export const MAX_NODE_MAJOR = 24;
+export const MAX_NODE_MAJOR = 25;
 export const PREFERRED_NODE_MAJOR = 24;
 function parseNodeVersion(version) {
     const [major = "0", minor = "0", patch = "0"] = version.replace(/^v/, "").split(".");

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=20.19.0 <25"
+    "node": ">=20.19.0 <26"
   },
   "bin": {
     "feynman": "bin/feynman.js"

package/scripts/check-node-version.mjs

@@ -1,5 +1,5 @@
 const MIN_NODE_VERSION = "20.19.0";
-const MAX_NODE_MAJOR = 24;
+const MAX_NODE_MAJOR = 25;
 const PREFERRED_NODE_MAJOR = 24;
 
 function parseNodeVersion(version) {

package/scripts/lib/npm-command.d.mts

@@ -0,0 +1,10 @@
+export type PackageManagerCommand = {
+	command: string;
+	args: string[];
+	shell?: boolean;
+};
+
+export declare function resolveAdjacentNpmCommand(
+	nodeExecutablePath?: string,
+	platform?: NodeJS.Platform,
+): PackageManagerCommand | undefined;

package/scripts/lib/npm-command.mjs

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// Windows cannot spawn `npm`/`npm.cmd` without a shell (EINVAL since the
+// CVE-2024-27980 hardening), and shell spawns with an args array trip
+// DEP0190. Preferring the npm-cli.js entry point next to the running Node
+// executable avoids both: it is a plain Node script spawn on every platform.
+export function resolveAdjacentNpmCommand(nodeExecutablePath = process.execPath, platform = process.platform) {
+	const executableDir = dirname(nodeExecutablePath);
+	if (platform === "win32") {
+		const npmCliPath = resolve(executableDir, "node_modules", "npm", "bin", "npm-cli.js");
+		if (existsSync(npmCliPath)) {
+			return { command: nodeExecutablePath, args: [npmCliPath] };
+		}
+		const npmCmdPath = resolve(executableDir, "npm.cmd");
+		return existsSync(npmCmdPath) ? { command: npmCmdPath, args: [], shell: true } : undefined;
+	}
+
+	const candidate = resolve(executableDir, "npm");
+	return existsSync(candidate) ? { command: candidate, args: [] } : undefined;
+}

package/scripts/lib/pi-model-registry-patch.d.mts

@@ -0,0 +1 @@
+export declare function patchPiModelRegistrySource(source: string): string;

package/scripts/lib/pi-model-registry-patch.mjs

@@ -0,0 +1,59 @@
+// Issue #171: a models.json provider header or API key containing characters
+// above U+00FF (e.g. Chinese text) makes undici's fetch throw the cryptic
+// "Cannot convert argument to a ByteString because the character at index N
+// has a value of M which is greater than 255" with no hint of which config
+// value caused it. Validate at request-assembly time and name the exact
+// provider and header instead; the surrounding try/catch in
+// getApiKeyAndHeaders turns the throw into a readable model error.
+const LATIN1_GUARD_HELPER = [
+	"function findNonLatin1CharIndex(value) {",
+	'    if (typeof value !== "string") return -1;',
+	"    for (let index = 0; index < value.length; index++) {",
+	"        if (value.charCodeAt(index) > 255) return index;",
+	"    }",
+	"    return -1;",
+	"}",
+	"function assertHeaderSafeRequestConfig(provider, apiKey, headers) {",
+	"    const apiKeyIndex = findNonLatin1CharIndex(apiKey);",
+	"    if (apiKeyIndex !== -1) {",
+	"        throw new Error(`The API key for provider \"${provider}\" contains a non-Latin-1 character at index ${apiKeyIndex} (code point ${apiKey.codePointAt(apiKeyIndex)}). HTTP headers cannot carry characters above U+00FF - check models.json or your stored auth for stray non-ASCII characters.`);",
+	"    }",
+	"    for (const [headerName, headerValue] of Object.entries(headers ?? {})) {",
+	'        const value = typeof headerValue === "string" ? headerValue : String(headerValue);',
+	"        const nameIndex = findNonLatin1CharIndex(headerName);",
+	"        const valueIndex = findNonLatin1CharIndex(value);",
+	"        if (nameIndex === -1 && valueIndex === -1) continue;",
+	"        const offending = nameIndex !== -1 ? headerName : value;",
+	"        const offendingIndex = nameIndex !== -1 ? nameIndex : valueIndex;",
+	"        throw new Error(`Header \"${headerName}\" for provider \"${provider}\" contains a non-Latin-1 character at index ${offendingIndex} (code point ${offending.codePointAt(offendingIndex)}). HTTP headers cannot carry characters above U+00FF - remove or URL-encode the value in models.json.`);",
+	"    }",
+	"}",
+].join("\n");
+
+const RETURN_ORIGINAL = [
+	"            return {",
+	"                ok: true,",
+	"                apiKey,",
+	"                headers: headers && Object.keys(headers).length > 0 ? headers : undefined,",
+	"            };",
+].join("\n");
+
+const RETURN_PATCHED = [
+	"            assertHeaderSafeRequestConfig(model.provider, apiKey, headers);",
+	RETURN_ORIGINAL,
+].join("\n");
+
+const HELPER_ANCHOR = "function formatValidationPath(error) {";
+
+export function patchPiModelRegistrySource(source) {
+	if (source.includes("function assertHeaderSafeRequestConfig(")) {
+		return source;
+	}
+	if (!source.includes(RETURN_ORIGINAL) || !source.includes(HELPER_ANCHOR)) {
+		return source;
+	}
+
+	let patched = source.replace(RETURN_ORIGINAL, RETURN_PATCHED);
+	patched = patched.replace(HELPER_ANCHOR, `${LATIN1_GUARD_HELPER}\n${HELPER_ANCHOR}`);
+	return patched;
+}

package/scripts/patch-embedded-pi.mjs

@@ -9,6 +9,8 @@ import { patchAlphaHubAuthSource } from "./lib/alpha-hub-auth-patch.mjs";
 import { patchAlphaHubSearchResultsSource, patchAlphaHubSearchSource } from "./lib/alpha-hub-search-patch.mjs";
 import { patchPiAgentCoreSource } from "./lib/pi-agent-core-patch.mjs";
 import { patchPiExtensionLoaderSource } from "./lib/pi-extension-loader-patch.mjs";
+import { resolveAdjacentNpmCommand } from "./lib/npm-command.mjs";
+import { patchPiModelRegistrySource } from "./lib/pi-model-registry-patch.mjs";
 import { patchPiPackageManagerSource } from "./lib/pi-package-manager-patch.mjs";
 import { patchPiEditorSource, patchPiInteractiveThemeSource, patchPiTuiSource } from "./lib/pi-tui-patch.mjs";
 import { PI_WEB_ACCESS_PATCH_TARGETS, patchPiWebAccessSource } from "./lib/pi-web-access-patch.mjs";
@@ -72,6 +74,7 @@ const interactiveModePath = piPackageRoot ? resolve(piPackageRoot, "dist", "mode
 const interactiveThemePath = piPackageRoot ? resolve(piPackageRoot, "dist", "modes", "interactive", "theme", "theme.js") : null;
 const extensionLoaderPath = piPackageRoot ? resolve(piPackageRoot, "dist", "core", "extensions", "loader.js") : null;
 const packageManagerPath = piPackageRoot ? resolve(piPackageRoot, "dist", "core", "package-manager.js") : null;
+const modelRegistryPath = piPackageRoot ? resolve(piPackageRoot, "dist", "core", "model-registry.js") : null;
 const agentLoopPath = piAgentCoreRoot ? resolve(piAgentCoreRoot, "dist", "agent-loop.js") : null;
 const tuiPath = piTuiRoot ? resolve(piTuiRoot, "dist", "tui.js") : null;
 const terminalPath = piTuiRoot ? resolve(piTuiRoot, "dist", "terminal.js") : null;
@@ -190,6 +193,18 @@ function resolvePackageManager() {
 	return null;
 }
 
+function resolvePackageManagerInvocation(packageManager) {
+	if (packageManager === "npm") {
+		const adjacent = resolveAdjacentNpmCommand();
+		if (adjacent) return adjacent;
+	}
+	const resolved = resolveExecutable(packageManager);
+	if (!resolved) return null;
+	// Windows cannot spawn .cmd/.bat shims without a shell (EINVAL).
+	const needsShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(resolved);
+	return { command: resolved, args: [], shell: needsShell };
+}
+
 function installWorkspacePackages(packageSpecs) {
 	const packageManager = resolvePackageManager();
 	if (!packageManager) {
@@ -199,8 +214,14 @@ function installWorkspacePackages(packageSpecs) {
 		return false;
 	}
 
-	const result = spawnSync(packageManager, createInstallCommand(packageManager, packageSpecs), {
+	const invocation = resolvePackageManagerInvocation(packageManager);
+	if (!invocation) {
+		process.stderr.write(`[feynman] could not resolve ${packageManager} executable for bundled package setup.\n`);
+		return false;
+	}
+	const result = spawnSync(invocation.command, [...invocation.args, ...createInstallCommand(packageManager, packageSpecs)], {
 		cwd: workspaceDir,
+		shell: invocation.shell,
 		stdio: ["ignore", "pipe", "pipe"],
 		timeout: 300000,
 		env: {
@@ -417,7 +438,11 @@ function restorePackagedWorkspace(packageSpecs) {
 	rmSync(workspaceDir, { recursive: true, force: true });
 	mkdirSync(resolve(appRoot, ".feynman"), { recursive: true });
 
-	const result = spawnSync("tar", ["-xzf", workspaceArchivePath, "-C", resolve(appRoot, ".feynman")], {
+	// Run tar from .feynman with relative paths: GNU tar (Git for Windows)
+	// treats absolute paths with a drive-letter colon ("C:\...") as remote
+	// host specs and fails with "Cannot connect ... resolve failed".
+	const result = spawnSync("tar", ["-xzf", "runtime-workspace.tgz", "-C", "."], {
+		cwd: resolve(appRoot, ".feynman"),
 		stdio: ["ignore", "ignore", "pipe"],
 		timeout: 300000,
 	});
@@ -725,6 +750,16 @@ for (const entryPath of [packageManagerPath, workspacePackageManagerPath].filter
 	}
 }
 
+const workspaceModelRegistryPath = resolveWorkspacePiFile("pi-coding-agent", "dist", "core", "model-registry.js");
+for (const entryPath of [modelRegistryPath, workspaceModelRegistryPath].filter(Boolean)) {
+	if (!existsSync(entryPath)) continue;
+	const source = readFileSync(entryPath, "utf8");
+	const patched = patchPiModelRegistrySource(source);
+	if (patched !== source) {
+		writeFileSync(entryPath, patched, "utf8");
+	}
+}
+
 for (const entryPath of [agentLoopPath, workspaceAgentLoopPath].filter(Boolean)) {
 	if (!existsSync(entryPath)) {
 		continue;
@@ -843,6 +878,23 @@ if (alphaHubIndexPath && existsSync(alphaHubIndexPath)) {
 	}
 }
 
+// The bundled workspace carries its own alpha-hub copy; patch it the same way
+// so search fixes apply regardless of which copy resolves at runtime.
+const workspaceAlphaHubLib = resolve(workspaceRoot, "@companion-ai", "alpha-hub", "src", "lib");
+for (const [fileName, patchFn] of [
+	["auth.js", patchAlphaHubAuthSource],
+	["alphaxiv.js", patchAlphaHubSearchSource],
+	["index.js", patchAlphaHubSearchResultsSource],
+]) {
+	const filePath = resolve(workspaceAlphaHubLib, fileName);
+	if (!existsSync(filePath)) continue;
+	const source = readFileSync(filePath, "utf8");
+	const patched = patchFn(source);
+	if (patched !== source) {
+		writeFileSync(filePath, patched, "utf8");
+	}
+}
+
 if (existsSync(piMemoryPath)) {
 	let source = readFileSync(piMemoryPath, "utf8");
 	const memoryOriginal = 'const MEMORY_DIR = join(homedir(), ".pi", "memory");';