Core Dependencies for the Feynman Runtime: A Complete Technical Breakdown

The Feynman runtime bundles a curated set of Pi ecosystem packages, Alpha-Hub integration, and essential build tools like esbuild and typebox, all pinned to specific versions via workspace preparation scripts to ensure reproducible AI agent execution.

The Feynman project by advaitpaliwal/feynman ships a self-contained runtime workspace designed for research-first AI agent execution. Unlike traditional Node.js applications that rely on node_modules, Feynman vendors its core dependencies into a deterministic archive using a sophisticated build pipeline defined in package.json and orchestrated through scripts/prepare-runtime-workspace.mjs.

Bundled Runtime Packages (The Pi Ecosystem Dependencies)

The foundation of the Feynman runtime consists of packages declared in the bundleDependencies field of package.json (lines 59-68 and 107-143). These packages are always included in the runtime archive and are patched or overridden at build time.

Core Pi Framework Packages

The runtime is built around the Pi ecosystem from Earendil Works, which provides the agent loop, inference, and UI capabilities:

• @earendil-works/pi-agent-core (0.85.1): Core agent loop and task orchestration logic.
• @earendil-works/pi-ai (0.85.1): LLM inference engines and prompt handling infrastructure.
• @earendil-works/pi-coding-agent (0.85.1): CLI-driven coding capabilities and sub-agent framework.
• @earendil-works/pi-tui (0.85.1): Terminal UI components for interactive research sessions.
• @earendil-works/pi-client (0.85.1): Client-side RPC for communicating with the embedded Pi server.
• @earendil-works/pi-server (0.85.1): Embedded HTTP server that hosts the Pi runtime environment.

Research and Infrastructure Dependencies

Beyond the Pi framework, the runtime includes specialized libraries for research workflows and low-level system operations:

• @advaitpaliwal/alpha-hub (0.1.4): Provides the Alpha-XIV research API used by the agent for external data retrieval.
• @opentelemetry/api (^1.9.1): Telemetry abstraction layer used throughout the runtime for observability.
• esbuild (0.28.2): Fast JavaScript bundler used to compile the runtime and its extensions at build time.
• typebox (1.3.27): Schema definition library for validated data exchange between components.
• undici (8.10.2): High-performance HTTP client utilized by the Pi server for external requests.
• brace-expansion (5.0.9): Utility library for glob-style pattern expansion in file operations.

These entries are explicitly listed in the bundleDependencies array to ensure they are vendored into the final runtime archive, regardless of the host system's Node.js environment.

Runtime Version Pinning and Overrides

Feynman guarantees deterministic builds through a strict version pinning strategy implemented in scripts/prepare-runtime-workspace.mjs (lines 166-194). During workspace preparation, the script injects a RUNTIME_PACKAGE_OVERRIDES object to enforce specific package versions and apply security patches.

Key pinned versions include:

• esbuild → 0.28.2 (critical for build reproducibility)
• brace-expansion → 5.0.9 (security and compatibility)
• OpenTelemetry packages → pinned to 0.222.0 or 2.11.0 (telemetry consistency)

This override mechanism ensures that even if upstream packages release new versions, the Feynman runtime always uses the tested, compatible versions required for stable agent execution.

How the Runtime Is Assembled

The runtime workspace assembly process follows a deterministic pipeline triggered by npm run build or directly through the prepare-runtime-workspace.mjs script. According to the source code in src/index.ts (lines 4-12), the build process executes four main phases:

1. Collect Package Specs: The readPackageSpecs function aggregates dependency requirements from user settings and the pinned override list.

2. Generate Workspace Manifest: The writeWorkspacePackageJson function creates a temporary package.json specifically for the runtime workspace, incorporating exact version specifications.

3. Install Exact Versions: The runWorkspaceNpm function executes npm ci or npm install --save-exact to populate the .feynman/npm directory with precisely versioned packages.

4. Apply Runtime Patches: The system applies specific corrections to bundled Pi components through patchBundledPiRuntimeCorrectness and patchBundledPiCliArgs to ensure CLI argument handling and runtime correctness align with Feynman's execution model.

This process creates a deterministic .tgz archive containing the complete, patched runtime environment.

Inspecting the Dependency Graph

You can programmatically inspect the exact runtime dependencies using the repository's own package.json structure. The following TypeScript example demonstrates how to extract the bundled runtime map:

import { readFileSync } from "node:fs";
import { resolve } from "node:path";

// Load the package.json of the repository
const pkg = JSON.parse(
  readFileSync(resolve(import.meta.dirname, "..", "package.json"), "utf8")
);

// Extract the core runtime dependencies from bundleDependencies
const coreRuntime = {
  // Bundled dependencies are always part of the runtime
  ...Object.fromEntries(
    pkg.bundleDependencies.map((name: string) => [name, pkg.dependencies[name]])
  ),
  // Explicitly include key runtime packages
  alphaHub: pkg.dependencies["@advaitpaliwal/alpha-hub"],
  piClient: pkg.dependencies["@earendil-works/pi-client"],
  piServer: pkg.dependencies["@earendil-works/pi-server"],
};

console.log("Core runtime dependencies:", coreRuntime);

This approach reveals the complete dependency graph that gets vendored into the runtime archive, excluding optional visualization libraries like d3 or 3dmol that are omitted from the minimal bundle.

Building the Runtime Workspace

To generate the runtime workspace with all core dependencies resolved and patched, execute the build command:

# Build the runtime workspace (executes the preparation script)

npm run build

This command triggers the following sequence:

1. Resolves package specifications (including the pinned versions from RUNTIME_PACKAGE_OVERRIDES)
2. Installs dependencies into the .feynman/npm workspace directory
3. Applies Pi-specific patches for runtime correctness and CLI argument handling
4. Creates a deterministic .tgz archive ready for distribution

The resulting archive contains the complete, self-contained runtime capable of executing the Feynman research agent without external npm registry access.

Summary

• Core Pi Ecosystem: The Feynman runtime depends on six @earendil-works/pi-* packages (agent-core, ai, coding-agent, tui, client, server) versioned at 0.85.1 to provide the agent loop, LLM inference, and embedded server capabilities.
• Research Integration: The @advaitpaliwal/alpha-hub package (0.1.4) provides the Alpha-XIV research API for external data access.
• Build Tools: Essential utilities including esbuild (0.28.2), typebox (1.3.27), undici (8.10.2), and brace-expansion (5.0.9) are bundled for compilation and HTTP operations.
• Version Pinning: The prepare-runtime-workspace.mjs script (lines 166-194) enforces exact versions through RUNTIME_PACKAGE_OVERRIDES to guarantee reproducible builds.
• Assembly Pipeline: The runtime is constructed via readPackageSpecs, writeWorkspacePackageJson, runWorkspaceNpm, and patching functions that modify bundled Pi components before final archive creation.

Frequently Asked Questions

What are the core Pi ecosystem packages in Feynman?

The Feynman runtime relies on six interconnected packages from Earendil Works: @earendil-works/pi-agent-core for task orchestration, pi-ai for LLM inference, pi-coding-agent for CLI capabilities, pi-tui for terminal interfaces, and pi-client/pi-server for RPC communication. All are pinned to version 0.85.1 according to the package.json bundleDependencies list.

How does Feynman ensure reproducible runtime builds?

Feynman enforces reproducibility through the RUNTIME_PACKAGE_OVERRIDES object in scripts/prepare-runtime-workspace.mjs, which pins critical packages like esbuild to 0.28.2 and OpenTelemetry libraries to specific versions. The build process uses npm install --save-exact to prevent version drift and creates a deterministic .tgz archive.

Where are the runtime dependencies defined in the Feynman source code?

The primary dependency declarations reside in package.json (lines 107-143 for dependencies and lines 59-68 for bundleDependencies). The assembly logic is implemented in scripts/prepare-runtime-workspace.mjs (lines 166-194 for overrides), while the entry point in src/index.ts (lines 4-12) initiates the build process.

What is the role of Alpha-Hub in the Feynman runtime?

@advaitpaliwal/alpha-hub (version 0.1.4) serves as the research API layer that enables the Feynman agent to access external Alpha-XIV research data. It is included as a bundled dependency in package.json and is essential for the agent's research-first execution capabilities, distinct from the core Pi framework infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}