Sandbox agent run: agents/chat ability unavailable when agents-api is double-loaded

[chubes4]

Summary

A wp-codebox.agent-sandbox-run step fails with:

AgentRuntimeError: The canonical agents/chat ability is not available inside the sandbox.

This is reproducible (2/2 clean runs) when the runtime is composed with a current Data Machine that vendors its own copy of agents-api. The agent never starts because wp_get_ability('agents/chat') returns null inside the sandbox-run eval.

Root cause

The generated sandbox PHP (packages/cli/src/agent-code.ts) loads agents-api as a standalone runtime plugin before Data Machine:

$plugins = array_merge(array(
    'agents-api/agents-api.php',        // standalone mount, loaded first
    'data-machine/data-machine.php',
    'data-machine-code/data-machine-code.php',
), ...);

Data Machine then requires its own vendored agents-api in data-machine.php:

require_once __DIR__ . '/vendor/wordpress/agents-api/agents-api.php';

agents-api guards against double-load:

if ( defined( 'AGENTS_API_LOADED' ) ) { return; }
define( 'AGENTS_API_LOADED', true );

So the standalone-mounted copy wins and Data Machine's vendored load is skipped. In the standalone-mounted path, agents/chat does not end up registered by the time the sandbox fires wp_abilities_api_init and calls wp_get_ability('agents/chat').

Evidence that agents-api itself is fine

Loaded the normal way — via Data Machine's vendored copy (data-machine/vendor/wordpress/agents-api/) — agents/chat registers and is executable. Confirmed with a WordPress PHPUnit test:

AGENTS_API_PATH=/wordpress/wp-content/plugins/data-machine/vendor/wordpress/agents-api/
agents/chat registered: yes, executable: yes

So this is a composition/load-order problem in the sandbox boot, not an agents-api bug.

Proposed fix

Do not mount/require agents-api as a separate runtime plugin when Data Machine already vendors it. Let Data Machine load its own vendored agents-api (the version it was built against), avoiding the double-load guard and version skew. Remove agents-api/agents-api.php from the standalone $plugins list and rely on data-machine.php's require_once .../vendor/wordpress/agents-api/agents-api.php.

This also fixes a latent version-skew risk: the standalone mount can be a different agents-api version than the one Data Machine vendors and expects.

Impact

This blocks WP Codebox coding agents end to end: the agent can't start, so no tool resolution or file edits happen. Related work that depends on this:

• Project write and git workspace tools for coding agents Extra-Chill/data-machine-code#606 (project write workspace tools)
• Add Claude Code provider plugin Extra-Chill/wp-coding-agents#197 (Claude Code provider structured tool calling)
• test: opt-in ability tools resolve for sandbox runs Extra-Chill/data-machine#2601 (resolver regression test proving the tool chain is otherwise correct)

Context

Found while landing the WP Codebox Claude Code coding-agent path. The tool-resolution chain (sandbox tool policy → ability projection → ToolPolicyResolver → provider) is proven correct in isolation; this agents-api double-load is the remaining end-to-end blocker.

[chubes4]

Closing — the original analysis here was wrong. The standalone agents-api/agents-api.php require is not a double-load bug; it was a fallback.

The real root cause is a breaking contract change in wp-codebox 0.8.0: buildAgentTaskRecipe now reads runtime component plugins (agents-api, data-machine, data-machine-code) from input.component_contracts (componentPlugins(input.component_contracts, artifacts)), and no longer from the legacy runtime_component_paths / data_machine_path / agents_api_path fields.

The Homeboy Extensions WP Codebox task runner was still emitting the legacy fields, so component_contracts was empty → componentPlugins([]) returned [] → the runtime components never mounted → agents/chat was unavailable in the sandbox and coding agents couldn't run.

Verified deterministically: wp-codebox 0.8.0's prepareRecipeExtraPlugins returns only the provider plugin for the legacy input shape, while 0.7.2 returned all four. The runtime.log confirmed only the provider mounted.

Fix is on the Homeboy Extensions side — emit component_contracts ({ slug, path, loadAs, activate }) in the wp-codebox/task-input/v1 payload. With that, all components mount as wp-codebox-runtime mu-plugins, agents/chat is available, and workspace_write executes successfully end to end. No wp-codebox change needed.