Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Bootstrap loads every class eagerly; rely on the classmap from #526 instead

Open
  • Is something wrong?
#560 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
65/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
php, wordpress
Domain
backend, build-system, performance

Research direction

Examine agents-api.php to see the current eager require_once statements. Identify the files with side effects (register-.php, functions-.php, guidelines.php) and the add_action calls. Understand the Composer classmap from PR #526. Test changes in a WordPress multisite setup, using opcache_get_status() to measure memory impact. Ensure version skew handling via AGENTS_API_LOADED is preserved.

Written by the indexing model from the issue text.

Description

Problem

agents-api.php require_onces every class and interface file under src/ (about 240 files on current main, 0.11.2) on every request, before any agent, chat or workflow is used. #526 added a lazy Composer classmap covering the full public class/interface surface, but the bootstrap still loads all of those classes eagerly, so the classmap never gets a chance to be lazy at runtime.

On a WordPress multisite where the package is bundled in a network-activated plugin (via Composer, as wordpress/agents-api), the package accounts for 249 cached scripts and about 5 MB of OPcache memory, measured with opcache_get_status(). On that server OPcache is full (128 MB), so this is memory taken from code that runs on every request. The chat is used on one page; every other request on every site pays for the whole runtime.

Proposal

Now that every class and interface is in the classmap, the bootstrap only needs to require_once files that have side effects or define functions:

  • src/*/register-*.php
  • src/Runtime/functions-*.php, src/Abilities/functions-ability-dispatch.php, src/Guidelines/guidelines.php
  • the add_action() calls at the end

and leave class-*.php / interface-*.php to the autoloader. Hook callbacks already reference classes by name as strings, so registration itself should not force them to load. Only a class actually touched during a request would be compiled and cached.

For the non-Composer (plain plugin) install, a small spl_autoload_register() over a generated class-to-file map (or the existing vendor/composer/autoload_classmap.php) would give the same behaviour.

Things to keep

  • Version skew. The AGENTS_API_LOADED branch currently loads missing symbols from the newer copy eagerly. With lazy loading, whichever copy's autoloader is registered first would win for classes not yet loaded, so the skew guarantee from #279 needs an equivalent (for example, the bootstrap that defines AGENTS_API_LOADED registering its own class map ahead of Composer's, or the skew branch registering a prepend autoloader for the newer copy).
  • Composer autoload outside WordPress stays inert, and PHPStan behaviour from #524/#526 is unchanged.

Happy to test a branch against our install and report OPcache numbers before and after.

Dominant language
PHP
Stars
33
Forks
8
Avg merge
24m
Merged PRs (30d)
18

Getting set up

We have not checked this project's setup files yet. Start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Automattic/agents-api

All issues in Automattic/agents-api

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.