Always show the Agents section in WP Explorer

[AllTerrainDeveloper]

Why

The Agents framework is opt-in behind the agents extended option (default off), and the WP Explorer integration lived inside the gated module load. So on every site that had never turned agents on, the section simply did not exist — and the one person who could enable it had no way to discover it from the window it belongs to.

What changed

includes/agents/my-wordpress.php now loads unconditionally, alongside guard.php. The section config gained two fields:

• enabled — mirrors the extended option. False means the REST routes are not registered, so the bundle must not fetch.
• canEnable — manage_options, since the Extended options block of the Features tab is admin-only.

With the flag off the section still opens and renders the same layout, entirely inert:

• warning notice at the top, with a Turn on Agents button that opens Preferences → Features (non-admins get "ask an administrator" instead)
• + Create agent rendered but disabled
• empty state reads "Agents are turned off" rather than "No agents yet"
• no listAgents(), no AI-status probe, no roles fetch — nothing that would 404
• the AI-connector warning is suppressed while off, so the one actionable notice isn't competing with a second one

Two helpers moved so the entity descriptor can be built while rest.php and identity.php are unloaded:

Helper	From	To
openstation_agents_user_can_{read,manage,invoke}()	rest.php	bootstrap.php
openstation_agent_avatar_url()	identity.php	bootstrap.php

Both files keep a comment at the old site explaining why, and a PHPUnit test asserts the declaring filename so they don't drift back.

Also: agentsConfigured() in the Send-to-agent menu now requires enabled, not just the presence of the config block — otherwise the cache warm-up would fire a guaranteed 404 on every site with the flag off.

What did not change

The read gate. openstation_agents_user_can_read (edit_posts) still decides whether the section is listed at all — subscribers and contributors see nothing, exactly as before.

Known limitation

Flipping the option from the notice does not live-refresh the open WP Explorer window; the section config is baked into the window payload, and the extended-options save is not one of the payloads the menu-refresh bridge diffs. The user needs a reload to see the section come alive. Worth a follow-up if it grates.

Tests

• tests/phpunit/tests/agentsMyWordpress.php (new, 8 tests) — entity listed with the flag off, withheld from non-readers, enabled / canEnable / canManage / canInvoke per role, helpers declared in the always-loaded bootstrap.
• tests/vitest/agents-renderer.test.ts — new framework turned off block: no fetch, is-disabled class, create button disabled-not-hidden, notice wiring to openOsSettings({ tabId: 'features' }), admin vs non-admin copy, empty-state heading.
• tests/vitest/agents-send-to.test.ts — does not warm while off.

Gates: npm run build, lint, typecheck, test:js (4013 passed), lint:php, test:php (2069 passed) all green.

Docs

docs/hooks-reference.md — the "one exception" note is now two, with the reasoning; the capability filters and openstation_agent_avatar_url() are marked as available while the feature is off. docs/examples/agents.md — the intro no longer says nothing survives the flag being off.

🤖 Generated with Claude Code