@companion-ai/feynman 0.5.21 → 0.5.23

package/.feynman/SYSTEM.md

@@ -17,6 +17,7 @@ Tools:
 
 Delegation:
 - Use the `researcher`, `writer`, `verifier`, and `reviewer` subagents when decomposition reduces context pressure or parallelizes evidence gathering. Keep delegation internal; do not make the user manage it.
+- To run several subagents in one call, write the workflow script to `outputs/.plans/<slug>-workflow.js`, and only after that write has succeeded, in a later tool call, call `subagent` with `workflow` set to that path. Do not use `workflow: true`: it needs a fenced block in the visible reply and fails when the block is only in your reasoning.
 - A workflow is finished only when its final artifact is on disk. Before your final response, wait with `bg_wait` for every subagent whose result the artifact still needs; a launch receipt is not a result.
 - For long workflows, write the plan to disk early and keep its task ledger and verification log current. If `CHANGELOG.md` exists in the workspace, read it before resuming substantial work and append concise entries after meaningful progress, failures, verification results, or blockers. Do not create it for one-shot tasks.
 - Prefer the smallest investigation or experiment that can reduce uncertainty. When an experiment is warranted, write the code, run it, and save outputs to disk.

package/RELEASES.md

@@ -6,6 +6,17 @@ GitHub release notes are generated from the matching `## vX.Y.Z` section in this
 
 ## Unreleased
 
+## v0.5.23 - 2026-10-02
+
+- **arXiv and PubMed rate limits.** arXiv asks for one request every three seconds, and parallel lookups got `429`; arXiv requests now run at that pace and a 429 is retried once. A PubMed `429`, which a subagent in another process or a shared IP can still trigger, is retried once after a pause.
+- Running several subagents at once from any workflow no longer fails with "workflow: true requires exactly one ```js workflow fenced block": Feynman now always writes the workflow script to a file and runs it by path, as `/deepresearch` already did.
+- Pi 1.0 is not in this release: pi-subagents 0.74.0 cannot start background subagents on it. The fix is merged upstream (nicobailon/pi-subagents#2634) and Feynman will move to Pi 1.0 once it is released.
+
+## v0.5.22 - 2026-10-01
+
+- **Launch warnings and the first-run telemetry notice show inside the session.** Feynman printed them to the terminal just before starting Pi, where Pi 1.0's fullscreen interface (coming in a later Feynman release) hides them for the whole session. They now appear in Pi's own interface: the Windows "No Bash found" warning, the small-local-model warning for research workflows, and the one-time telemetry disclosure. A one-shot `--prompt` run still prints them to stderr.
+- `feynman doctor` reports Pi's new `quietStartup: "header"` setting as "header only" instead of "disabled".
+
 ## 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.

package/dist/pi/launch.js

@@ -41,15 +41,10 @@ export async function runPi(options, args, env, stdin = "inherit") {
     });
 }
 export async function launchPiChat(options) {
+    let telemetryNotice;
     if (process.stdout.isTTY && options.mode !== "rpc") {
         process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
-        // Clearing the screen erased the first-run notice printed at startup.
-        const telemetryNotice = telemetryFirstRunNotice();
-        if (telemetryNotice)
-            process.stderr.write(`${telemetryNotice}\n`);
-    }
-    if (options.preLaunchNotice) {
-        process.stdout.write(`${options.preLaunchNotice}\n`);
+        telemetryNotice = telemetryFirstRunNotice();
     }
     const executables = await resolveAllExecutables();
     ensureFeynmanCommandShim(options.appRoot, options.feynmanAgentDir);
@@ -59,5 +54,13 @@ export async function launchPiChat(options) {
     // explicit prompt forever.
     const explicitPrompt = Boolean(options.oneShotPrompt || options.initialPrompt);
     const stdin = explicitPrompt && options.mode !== "rpc" && !process.stdin.isTTY ? "ignore" : "inherit";
-    process.exitCode = await runPi(options, buildPiArgs(options), buildPiEnv(options, executables), stdin);
+    // Pi's fullscreen UI hides anything printed before it starts, so the TUI
+    // session shows these itself; one-shot and JSON runs print them as before.
+    const notice = [telemetryNotice, options.preLaunchNotice].filter(Boolean).join("\n");
+    const tui = options.mode !== "rpc" && options.mode !== "json" && !options.oneShotPrompt;
+    if (notice && !tui)
+        process.stderr.write(`${notice}\n`);
+    const env = buildPiEnv(options, executables);
+    env.FEYNMAN_LAUNCH_NOTICE = notice && tui ? notice : undefined;
+    process.exitCode = await runPi(options, buildPiArgs(options), env, stdin);
 }

package/dist/setup/doctor.js

@@ -171,7 +171,7 @@ export async function runDoctor(options) {
     for (const line of formatPiWebAccessDoctorLines()) {
         console.log(line);
     }
-    console.log(`quiet startup: ${settings.quietStartup === true ? "enabled" : "disabled"}`);
+    console.log(`quiet startup: ${settings.quietStartup === "header" ? "header only" : settings.quietStartup === true ? "enabled" : "disabled"}`);
     console.log(`theme: ${typeof settings.theme === "string" ? settings.theme : "not set"}`);
     if (missingPiBits.length > 0) {
         console.log("pi runtime: missing files");

package/extensions/research-tools/launch-notice.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export function registerLaunchNotice(pi: ExtensionAPI): void {
+	pi.on("session_start", (_event, ctx) => {
+		const notice = process.env.FEYNMAN_LAUNCH_NOTICE;
+		delete process.env.FEYNMAN_LAUNCH_NOTICE;
+		if (notice && ctx.mode === "tui" && ctx.hasUI) {
+			// Pi labels warnings itself.
+			ctx.ui.notify(notice.replace(/^Warning: /gm, ""), "warning");
+		}
+	});
+}

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

@@ -1,5 +1,7 @@
 import { XMLParser } from "fast-xml-parser";
 
+import { createRequestPacer } from "./request-pacer.js";
+
 type SearchParams = {
 	query: string;
 };
@@ -27,20 +29,32 @@ function cleanQuery(query: string): string {
 	return clean;
 }
 
+// arXiv's API terms ask for no more than one request every three seconds, and
+// parallel lookups got 429. Requests run one after another at that pace, and a
+// 429 is retried once after the same wait.
+const arxivPacer = createRequestPacer();
+export const ARXIV_MIN_GAP_MS = 3000;
+
 async function fetchText(url: URL, accept: string): Promise<string> {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-	try {
-		const response = await fetch(url, {
-			headers: { accept },
-			signal: controller.signal,
+	for (let attempt = 0; ; attempt += 1) {
+		const result = await arxivPacer(ARXIV_MIN_GAP_MS, async () => {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+			try {
+				const response = await fetch(url, {
+					headers: { accept },
+					signal: controller.signal,
+				});
+				if (response.status === 429 && attempt === 0) return undefined;
+				if (!response.ok) {
+					throw new Error(`${url.hostname} request failed: ${response.status} ${response.statusText}`);
+				}
+				return await response.text();
+			} finally {
+				clearTimeout(timeout);
+			}
 		});
-		if (!response.ok) {
-			throw new Error(`${url.hostname} request failed: ${response.status} ${response.statusText}`);
-		}
-		return response.text();
-	} finally {
-		clearTimeout(timeout);
+		if (result !== undefined) return result;
 	}
 }
 

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

@@ -98,23 +98,32 @@ function prune<T extends Record<string, unknown>>(record: T): Record<string, unk
 
 // The abort timer stays armed across the body read: fetch resolves on headers,
 // so clearing it earlier would leave a stalled body hanging forever.
+// Pacing keeps one process under NCBI's limit, but subagents run in their own
+// processes and an IP can be shared, so a 429 is retried once after a pause.
+const NCBI_RETRY_MS = 1500;
+
 async function send<T>(url: URL, accept: string, read: (response: Response) => Promise<T>): Promise<T> {
-	return withNcbiRateLimit(url, async () => {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
-		try {
-			const response = await fetch(url, {
-				headers: {
-					accept,
-					"user-agent": "feynman-pubmed-tools/1.0 (https://github.com/Companion-Inc/feynman)",
-				},
-				signal: controller.signal,
-			});
-			return await read(response);
-		} finally {
-			clearTimeout(timeout);
-		}
-	});
+	for (let attempt = 0; ; attempt += 1) {
+		const result = await withNcbiRateLimit(url, async (): Promise<{ retry: true } | { value: T }> => {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+			try {
+				const response = await fetch(url, {
+					headers: {
+						accept,
+						"user-agent": "feynman-pubmed-tools/1.0 (https://github.com/Companion-Inc/feynman)",
+					},
+					signal: controller.signal,
+				});
+				if (response.status === 429 && attempt === 0) return { retry: true };
+				return { value: await read(response) };
+			} finally {
+				clearTimeout(timeout);
+			}
+		});
+		if ("value" in result) return result.value;
+		await new Promise((resolve) => setTimeout(resolve, NCBI_RETRY_MS));
+	}
 }
 
 function assertOk(response: Response): void {

package/extensions/research-tools.ts

@@ -7,6 +7,7 @@ import { registerDocxFallback } from "./research-tools/docx-fallback.js";
 import { installFeynmanHeader } from "./research-tools/header.js";
 import { registerHelpCommand } from "./research-tools/help.js";
 import { registerHuggingFaceTools } from "./research-tools/huggingface.js";
+import { registerLaunchNotice } from "./research-tools/launch-notice.js";
 import { registerInitCommand, registerOutputsCommand } from "./research-tools/project.js";
 import { registerServiceTierControls } from "./research-tools/service-tier.js";
 import { registerScienceDatabaseTools } from "./research-tools/science-databases.js";
@@ -27,6 +28,7 @@ export default function researchTools(pi: ExtensionAPI): void {
 	registerDocxFallback(pi);
 	registerHelpCommand(pi);
 	registerInitCommand(pi);
+	registerLaunchNotice(pi);
 	registerOutputsCommand(pi);
 	registerServiceTierControls(pi);
 	registerScienceDatabaseTools(pi);

package/package.json

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

package/prompts/deepresearch.md

@@ -68,7 +68,7 @@ If subagents were chosen:
 - Keep `subagent` tool-call JSON small and valid.
 - Do not place multi-paragraph instructions inside the `subagent` JSON.
 - Use only supported `subagent` keys. Do not add extra keys such as `artifacts` unless the tool schema explicitly exposes them.
-- For parallel evidence gathering, write a workflow script that returns `await runs.all(...)` to `outputs/.plans/<slug>-workflow.js` with the write tool. After the write succeeds, call `subagent` with `workflow: "./outputs/.plans/<slug>-workflow.js"`, `async: true`, and `globalConcurrencyLimit: 4`. Each item needs a unique stable `key`, plus its agent, short task, and output path. Do not pass the script text inside the tool call.
+- For parallel evidence gathering, write a workflow script that returns `await runs.all(...)` to `outputs/.plans/<slug>-workflow.js` with the write tool. After the write succeeds, in a later tool call (not in parallel with the write), call `subagent` with `workflow: "./outputs/.plans/<slug>-workflow.js"`, `async: true`, and `globalConcurrencyLimit: 4`. Each item needs a unique stable `key`, plus its agent, short task, and output path. Do not pass the script text inside the tool call.
 - Read the ordered result array and record each child's `ok`, error, and returned output/artifact paths. Ordinary child failures are collected by `runs.all`; validation or infrastructure failure can still fail the workflow. Do not assume every output exists.
 - Prefer broad guidance such as "use paper search and web search"; if a PDF parser or paper fetch fails, the researcher must continue from metadata, abstracts, and web sources and mark PDF parsing as blocked.
 

package/prompts/summarize.md

@@ -116,7 +116,7 @@ Briefly summarize: "Source is ~<chars> chars -> <N> chunks -> <N> researcher sub
 
 ### 3c. Dispatch researcher subagents
 
-Use one async workflow with a stable key for each chunk and a concurrency limit of four: write the script to `outputs/.plans/<slug>-workflow.js` with the write tool, then, after the write succeeds, call `subagent` with `{ "workflow": "./outputs/.plans/<slug>-workflow.js", "async": true, "globalConcurrencyLimit": 4 }`. Expand the example item below for the actual chunk inventory; retain the single-source restriction and explicit output declaration for every child.
+Use one async workflow with a stable key for each chunk and a concurrency limit of four: write the script to `outputs/.plans/<slug>-workflow.js` with the write tool, then, after the write succeeds, in a later tool call, call `subagent` with `{ "workflow": "./outputs/.plans/<slug>-workflow.js", "async": true, "globalConcurrencyLimit": 4 }`. Expand the example item below for the actual chunk inventory; retain the single-source restriction and explicit output declaration for every child.
 
 ```js
 return await runs.all([