@companion-ai/feynman 0.5.9 → 0.5.11

package/README.md

@@ -10,176 +10,70 @@
   <a href="https://deepwiki.com/Companion-Inc/feynman"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
 </p>
 
----
+## Install
 
-### Installation
-
-**macOS / Linux:**
+macOS / Linux:
 
 ```bash
 curl -fsSL https://feynman.is/install | bash
 ```
 
-**Windows (PowerShell):**
+Windows (PowerShell):
 
 ```powershell
 irm https://feynman.is/install.ps1 | iex
 ```
 
-The one-line installer fetches the latest tagged release as a standalone bundle with its own Node.js runtime and verifies its SHA-256 before installing. To pin a version, pass it explicitly, for example `curl -fsSL https://feynman.is/install | bash -s -- 0.5.3`. Rerun the installer to upgrade; `feynman update` only updates optional Pi packages you installed.
-
-**npm alternative** (uses your local Node.js `>=22.22.0`):
-
-```bash
-npm install -g @companion-ai/feynman
-```
-
-If you installed the interim `@advaitpaliwal/feynman` package, migrate once:
-
-```bash
-npm uninstall -g @advaitpaliwal/feynman
-npm install -g @companion-ai/feynman
-```
-
-Then run `feynman setup` to sign in to a model provider. To use Feynman in an ACP editor such as Zed, run it through [pi-acp](https://github.com/svkozak/pi-acp): `"agent_servers": { "Feynman": { "command": "npx", "args": ["-y", "pi-acp"], "env": { "PI_ACP_PI_COMMAND": "feynman" } } }`. See the [installation guide](https://feynman.is/docs/getting-started/installation) for uninstalling and the [setup guide](https://feynman.is/docs/getting-started/setup) for local models (LM Studio, LiteLLM, Ollama, vLLM) and Amazon Bedrock.
-
-### Skills Only
-
-If you want just the research skills without the full terminal app:
+Or with npm and Node.js 22.22 or newer: `npm install -g @companion-ai/feynman`.
 
-**macOS / Linux:**
+Then sign in to a model provider:
 
 ```bash
-curl -fsSL https://feynman.is/install-skills | bash
+feynman setup
 ```
 
-**Windows (PowerShell):**
+The [installation guide](https://feynman.is/docs/getting-started/installation) covers pinned versions, uninstalling, and the skills-only bundle for Codex and OpenCode. The [setup guide](https://feynman.is/docs/getting-started/setup) covers local models and editors such as Zed.
 
-```powershell
-irm https://feynman.is/install-skills.ps1 | iex
-```
-
-That installs the skill library into `~/.codex/skills/feynman` for Codex. For other targets, pass a scope:
+## Use
 
 ```bash
-curl -fsSL https://feynman.is/install-skills | bash -s -- --codex     # ~/.codex/skills/feynman (default)
-curl -fsSL https://feynman.is/install-skills | bash -s -- --repo      # .agents/skills/feynman in the current repo
-curl -fsSL https://feynman.is/install-skills | bash -s -- --opencode  # .opencode/skills/feynman in the current repo
-```
-
-```powershell
-& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope Codex     # or -Scope Repo, -Scope OpenCode
+feynman "what do we know about scaling laws"
+feynman lit "RLHF alternatives"
+feynman deepresearch "mechanistic interpretability"
 ```
 
-These installers download the bundled `skills/` and `prompts/` trees plus the repo guidance files referenced by those skills. They do not install the Feynman terminal, bundled Node runtime, auth storage, or Pi packages.
-
----
-
-### What you type → what happens
-
-```
-$ feynman "what do we know about scaling laws"
-→ Searches papers and the web, answers with cited sources
-
-$ feynman deepresearch "mechanistic interpretability"
-→ Plan-first investigation with parallel researchers, synthesis, and citation verification
-
-$ feynman lit "RLHF alternatives"
-→ Literature review with consensus, disagreements, open questions, and lab/PI corpus mode when the input names a research group
-
-$ feynman audit 2401.12345
-→ Compares paper claims against the public codebase
-
-$ feynman replicate "chain-of-thought improves math"
-→ Plans replication checks and runs them only after an explicit environment choice
-
-$ feynman recipe "fine-tune a small model for math reasoning"
-→ Finds ranked, implementable ML training recipes from papers, datasets, docs, and code
-```
-
----
-
-### Workflows
-
-Ask naturally or use slash commands as shortcuts.
-
-| Command | What it does |
+| Workflow | What it does |
 | --- | --- |
-| `/deepresearch <topic>` | Source-heavy multi-agent investigation |
-| `/lit <topic-or-lab>` | Literature review from paper search and primary sources; lab/PI inputs map publication trajectories and originality-ranked papers |
-| `/review <artifact>` | Research review with severity and revision plan |
-| `/audit <item>` | Paper vs. codebase mismatch audit |
-| `/replicate <paper>` | Plan replication checks; execute only after choosing an environment |
-| `/recipe <task-or-paper>` | Ranked ML training recipes with dataset, method, code, and verification status |
+| `/deepresearch <topic>` | Planned investigation with parallel researchers and citation checks |
+| `/lit <topic or lab>` | Literature review: consensus, disagreements, open questions |
+| `/review <paper or draft>` | Critique with severity levels and a revision plan |
+| `/audit <paper>` | Paper claims compared with its public code |
+| `/replicate <paper>` | Replication plan; runs only after you choose an environment |
+| `/recipe <task>` | Ranked ML training recipes with datasets and code |
 | `/compare <topic>` | Source comparison matrix |
 | `/draft <topic>` | Paper-style draft from research findings |
-| `/autoresearch <idea>` | Bounded experiment loop with benchmark evidence |
-| `/summarize <source>` | Summarize a paper, report, repo, or PDF without loading it raw into context |
-| `/btw <question>` | Side conversation while the main research agent is busy, with optional handoff back into the main thread |
-| `/outputs` | Browse all research artifacts |
-
----
-
-### Agents
-
-Four bundled research agents, invoked by workflow prompts when decomposition helps.
-
-- **Researcher** — gather evidence across papers, web, repos, docs
-- **Reviewer** — internal research critique with severity-graded feedback
-- **Writer** — structured drafts from research notes
-- **Verifier** — inline citations, source URL verification, dead link cleanup
+| `/autoresearch <idea>` | Bounded experiment loop against a benchmark |
+| `/summarize <source>` | Summary of a paper, repository, or PDF |
 
----
+Results are saved to `outputs/` (drafts to `papers/`). `/lit`, `/deepresearch`, and `/recipe` also write a provenance file listing the sources used and what was verified.
 
-### Skills & Tools
+## Sources
 
-- **[alphaXiv](https://www.alphaxiv.org/)** — paper search, Q&A, code reading, and annotations (via Feynman's `alpha` tools and `feynman alpha` command)
-- **Literature databases** — read-only Semantic Scholar, OpenAlex, arXiv ID lookup, PubMed, Europe PMC full text, bioRxiv/medRxiv, and Crossref, with stable identifiers. Set the free `OPENALEX_API_KEY` ([create one](https://openalex.org/settings/api)) and optionally `SEMANTIC_SCHOLAR_API_KEY` ([request one](https://www.semanticscholar.org/product/api#api-key-form)) to use your own rate limits
-- **[Hugging Face Hub](https://huggingface.co/docs/hub/api)** — dataset metadata, split/schema inspection, and small file reads from model, dataset, and Space repos
-- **Web research** — search, page fetching, and PDF extraction through [pi-web-access](https://github.com/nicobailon/pi-web-access); Exa works without a key, and `feynman search set` configures Perplexity, Exa, or Gemini
-- **Documents** — local PDF and office-document parsing through [pi-docparser](https://github.com/maxedapps/pi-docparser)
-- **Compute** — Docker, plus Modal or RunPod when their CLIs are installed, for replication and experiment runs you explicitly approve
+Feynman searches alphaXiv, Semantic Scholar, OpenAlex, arXiv, PubMed, Europe PMC, bioRxiv, medRxiv, Crossref, the web, and Hugging Face, and reads local PDFs and documents. Free `OPENALEX_API_KEY` and `SEMANTIC_SCHOLAR_API_KEY` keys avoid the shared rate limits. It runs on stock [Pi](https://github.com/earendil-works/pi) with four research agents: researcher, verifier, reviewer, and writer.
 
----
+## Telemetry
 
-### How it works
+Feynman sends anonymous usage data to PostHog: commands, workflows, tools, models, token counts, and errors with their messages and stack traces (your home folder shown as `~`). It never sends prompts, model output, paper content, or tool arguments. Turn it off with `FEYNMAN_TELEMETRY=off`. [What is sent](https://feynman.is/docs/getting-started/configuration#telemetry)
 
-Feynman runs on stock [Pi](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`). Its prompts, skills, agents, and research tools load as a Pi [package](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) alongside the bundled `pi-subagents`, `pi-web-access`, `pi-docparser`, and `pi-btw` packages. Paper search and analysis use [alphaXiv](https://www.alphaxiv.org/). Research claims link to papers, docs, or repos with direct URLs.
-
----
-
-### Telemetry
-
-Feynman sends anonymous usage telemetry to PostHog by default and prints a one-time notice on first run. It sends commands, workflow names and outcomes, tool names, model and provider names, token counts, latency, and error messages with stack traces (home folder shown as `~`) under a random install ID. It never sends prompts, model output, paper content, or tool arguments. Set `FEYNMAN_TELEMETRY=off` (or `DO_NOT_TRACK=1`) to disable it; `feynman status` shows the current setting. The full event list is in the [configuration docs](https://feynman.is/docs/getting-started/configuration#telemetry).
-
----
-
-### Star History
-
-<a href="https://www.star-history.com/?repos=Companion-Inc%2Ffeynman&type=date&legend=top-left">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Companion-Inc/feynman&type=date&theme=dark&legend=top-left" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Companion-Inc/feynman&type=date&legend=top-left" />
-    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Companion-Inc/feynman&type=date&legend=top-left" />
-  </picture>
-</a>
-
----
-
-The bundled Pi packages are pinned and update with Feynman, not through `feynman update`. See the [package stack](https://feynman.is/docs/reference/package-stack) and [release notes](https://feynman.is/docs/reference/releases).
-
-### Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
+## Contributing
 
 ```bash
 git clone https://github.com/Companion-Inc/feynman.git
 cd feynman
-nvm use || nvm install
 npm install
 npm test
-npm run typecheck
-npm run build
 ```
 
-[Docs](https://feynman.is/docs) · [Release Notes](RELEASES.md) · [MIT License](LICENSE)
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+[Docs](https://feynman.is/docs) · [Release notes](RELEASES.md) · [MIT License](LICENSE)

package/RELEASES.md

@@ -6,6 +6,17 @@ GitHub release notes are generated from the matching `## vX.Y.Z` section in this
 
 ## Unreleased
 
+## v0.5.11 - 2026-09-27
+
+- **Crossref lookups no longer fail in bursts.** Crossref's public pool allows one request at a time, one per second, and parallel DOI checks (the verifier cross-checks every citation) got `429 Too Many Requests` on most calls. Crossref requests now run one after another at the pool's pace. Set `CROSSREF_MAILTO` to your email for Crossref's faster polite pool; a 429 now says so instead of a generic "Science database request failed".
+- Telemetry's "wrote output" flag no longer misses a report written in the first second of a run on filesystems that round file times (HFS+, FAT, ext3).
+
+## v0.5.10 - 2026-09-27
+
+- **Semantic Scholar understands the documented query syntax.** A `semantic:` prefix and `year_from=`/`year_to=` flags, which the model reuses from the OpenAlex examples, were sent to Semantic Scholar as search text and returned unrelated papers or nothing. They now become Semantic Scholar's own year filter.
+- **The startup header lists only Feynman's workflows.** It also listed prompt commands that pi-subagents ships, such as `/parallel-review` and `/review-loop`.
+- **Cleaner README and landing page** with a current screenshot, and a shorter configuration page.
+
 ## v0.5.9 - 2026-09-27
 
 - **Subagents keep their search tools in the foreground.** A `researcher` or `verifier` launched in the foreground failed at once because foreground children never load the parent's extensions, so `web_search`, `fetch_content`, and `feynman_science_database_search` were missing. Feynman now points pi-subagents' `defaultSubagentOnlyExtensions` setting at its research tools and pi-web-access, so every child has them, in the foreground or background.

package/extensions/research-tools/header.ts

@@ -6,6 +6,8 @@ import { resolve as resolvePath } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
+import { readPromptSpecs } from "../../metadata/commands.mjs";
+
 import {
 	APP_ROOT,
 	FEYNMAN_AGENT_LOGO,
@@ -161,9 +163,11 @@ function detectSystemResources(): SystemResources {
 
 type WorkflowInfo = { name: string; description: string };
 
-function getResearchWorkflows(pi: ExtensionAPI): WorkflowInfo[] {
+// Only Feynman's own workflows; other packages (pi-subagents) also ship prompt commands.
+export function getResearchWorkflows(pi: Pick<ExtensionAPI, "getCommands">, appRoot = APP_ROOT): WorkflowInfo[] {
+	const feynmanWorkflows = new Set(readPromptSpecs(appRoot).map((spec) => spec.name));
 	return pi.getCommands()
-		.filter((cmd) => cmd.source === "prompt")
+		.filter((cmd) => cmd.source === "prompt" && feynmanWorkflows.has(cmd.name))
 		.map((cmd) => ({ name: `/${cmd.name}`, description: cmd.description ?? "" }))
 		.sort((a, b) => a.name.localeCompare(b.name));
 }

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

@@ -137,6 +137,25 @@ function crossrefAuthors(value: unknown): string[] {
 		.slice(0, 8);
 }
 
+// Crossref's public pool allows one request at a time, one per second
+// (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;
+
+export function withCrossrefPacing<T>(polite: boolean, run: () => Promise<T>): Promise<T> {
+	const minGapMs = polite ? 350 : 1000;
+	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;
+}
+
 async function searchCrossref(params: ScienceDatabaseSearchParams): Promise<Record<string, unknown>> {
 	const query = cleanQuery(params.query);
 	const limit = safeLimit(params.limit);
@@ -148,7 +167,17 @@ async function searchCrossref(params: ScienceDatabaseSearchParams): Promise<Reco
 		select: "DOI,title,published-print,published-online,issued,container-title,author,is-referenced-by-count,URL,type",
 		...(mailto ? { mailto } : {}),
 	}).toString();
-	const payload = recordValue(await fetchJson(url));
+	let payload: Record<string, unknown>;
+	try {
+		payload = recordValue(await withCrossrefPacing(Boolean(mailto), () => fetchJson(url)));
+	} catch (error) {
+		if (!(error instanceof ScienceDatabaseRequestError) || error.status !== 429) throw error;
+		throw new Error(
+			mailto
+				? "Crossref rate-limited this request (HTTP 429). Wait a few seconds and retry, or look the DOI up with source openalex."
+				: "Crossref's public pool rate-limited this request (HTTP 429). Set CROSSREF_MAILTO to your email for Crossref's faster polite pool, wait and retry, or look the DOI up with source openalex.",
+		);
+	}
 	const message = recordValue(payload.message);
 	const results = arrayValue(message.items).flatMap((item) => {
 		const record = recordValue(item);
@@ -257,12 +286,31 @@ function truncateText(value: string | undefined, maxChars: number): string | und
 	return `${value.slice(0, maxChars).trimEnd()}…`;
 }
 
-function semanticScholarSearchUrl(query: string, limit: number, sort: string): URL {
+// The model reuses the OpenAlex syntax this tool documents (a `semantic:`
+// prefix, year_from=/year_to= flags). Sent as text, it returned junk or zero
+// results; map it to Semantic Scholar's own year filter instead.
+export function parseSemanticScholarQuery(raw: string): { query: string; year?: string } {
+	let from = "";
+	let to = "";
+	const query = raw
+		.replace(/^\s*semantic:\s*/i, "")
+		.replace(/\byear_(from|to)=(\d{4})\b/gi, (_match, kind: string, year: string) => {
+			if (kind.toLowerCase() === "from") from = year;
+			else to = year;
+			return " ";
+		})
+		.replace(/\s+/g, " ")
+		.trim();
+	return from || to ? { query, year: `${from}-${to}` } : { query };
+}
+
+function semanticScholarSearchUrl(query: string, limit: number, sort: string, year?: string): URL {
 	const relevance = sort === "relevance";
 	const url = new URL(`${SEMANTIC_SCHOLAR_BASE}/paper/search${relevance ? "" : "/bulk"}`);
 	url.search = new URLSearchParams({
 		query,
 		fields: SEMANTIC_SCHOLAR_FIELDS,
+		...(year ? { year } : {}),
 		...(relevance ? { limit: String(limit) } : { sort }),
 	}).toString();
 	return url;
@@ -271,10 +319,10 @@ function semanticScholarSearchUrl(query: string, limit: number, sort: string): U
 // Bulk search sorted by citation count surfaces seminal papers that relevance
 // ranking misses; it returns up to 1,000 rows, so only the top `limit` are kept.
 async function searchSemanticScholar(params: ScienceDatabaseSearchParams): Promise<Record<string, unknown>> {
-	const query = cleanQuery(params.query);
+	const { query, year } = parseSemanticScholarQuery(cleanQuery(params.query));
 	const limit = safeLimit(params.limit);
 	let sort = params.sort === "relevance" ? "relevance" : params.sort === "pub_date" ? "publicationDate:desc" : "citationCount:desc";
-	const endpoints = [semanticScholarSearchUrl(query, limit, sort)];
+	const endpoints = [semanticScholarSearchUrl(query, limit, sort, year)];
 	let note: string | undefined;
 	let payload: Record<string, unknown>;
 	try {
@@ -284,7 +332,7 @@ async function searchSemanticScholar(params: ScienceDatabaseSearchParams): Promi
 		const anonymous = !process.env.SEMANTIC_SCHOLAR_API_KEY?.trim();
 		if (sort !== "relevance" || !anonymous || !(error instanceof ScienceDatabaseRequestError) || error.status !== 429) throw error;
 		sort = "citationCount:desc";
-		endpoints.push(semanticScholarSearchUrl(query, limit, sort));
+		endpoints.push(semanticScholarSearchUrl(query, limit, sort, year));
 		note = `Relevance search was rate-limited (HTTP 429) on Semantic Scholar's shared anonymous pool, so these are citation-sorted bulk results. A free SEMANTIC_SCHOLAR_API_KEY avoids this: ${SEMANTIC_SCHOLAR_KEY_URL}`;
 		payload = recordValue(await fetchSemanticScholar(endpoints[1]!));
 	}
@@ -314,6 +362,7 @@ async function searchSemanticScholar(params: ScienceDatabaseSearchParams): Promi
 		schema: "feynman.scienceDatabaseSearch.v1",
 		source: "semanticscholar",
 		query,
+		...(year ? { year } : {}),
 		sort,
 		...(note ? { note } : {}),
 		totalCount: numberValue(payload.total) ?? results.length,

package/extensions/research-tools/telemetry.ts

@@ -95,6 +95,11 @@ export function workflowName(text: string, workflows: ReadonlySet<string>): stri
 	return name && workflows.has(name) ? name : "chat";
 }
 
+// Filesystems stamp modification times from a coarse clock, and some (HFS+,
+// FAT, ext3) round them to whole seconds, so a file written just after the run
+// started can carry an earlier mtime. Allow for that rounding.
+const MTIME_TOLERANCE_MS = 2000;
+
 export function wroteResearchOutput(cwd: string, since: number): boolean {
 	let scanned = 0;
 	for (const dir of OUTPUT_DIRS) {
@@ -108,7 +113,7 @@ export function wroteResearchOutput(cwd: string, since: number): boolean {
 			if (++scanned > OUTPUT_SCAN_LIMIT) return false;
 			try {
 				const stats = statSync(join(cwd, dir, entry));
-				if (stats.isFile() && stats.mtimeMs >= since) return true;
+				if (stats.isFile() && stats.mtimeMs >= since - MTIME_TOLERANCE_MS) return true;
 			} catch {}
 		}
 	}

package/package.json

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