Add bearer token request authentication

[chubes4]

Summary

• Add first-class BearerTokenRequestAuthentication support for providers that use bearer-token auth.
• Add RequestAuthenticationMethod::bearerToken() / BEARER_TOKEN and registry validation for the new auth type.
• Keep explicit registry auth overrides while avoiding provider-supplied arbitrary auth instances.
• Update focused registry tests and mocks for bearer-token provider authentication.

Fixes #237.

Testing

• composer phpunit -- --filter ProviderRegistryTest - passed, 34 tests / 66 assertions.
• composer lint - passed.

Downstream proof

• Verified with WordPress/ai-provider-for-openai#28 through Homeboy Lab offload to a Linux runner.
• WP Codebox launched a WordPress sandbox with the Codex subscription profile.
• A native Codex-backed agent ran headlessly through Agents API/Data Machine workspace tools and completed successfully.
• Proof run: agent-task-b8f6e825-7f37-4d35-84f0-47927f851899.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Drafting the bearer-token auth primitive, registry wiring, focused test coverage, and local/downstream verification. Chris remains responsible for review and acceptance.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: chubes4 <[email protected]>
Co-authored-by: felixarntz <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.56%. Comparing base (99a65e8) to head (d3d210c).
⚠️ Report is 4 commits behind head on trunk.

Files with missing lines	Patch %	Lines
...ders/Http/DTO/BearerTokenRequestAuthentication.php	0.00%	25 Missing ⚠️
...oviders/Http/Enums/RequestAuthenticationMethod.php	0.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #238      +/-   ##
============================================
- Coverage     88.12%   87.56%   -0.57%     
- Complexity     1213     1224      +11     
============================================
  Files            60       62       +2     
  Lines          3934     3972      +38     
============================================
+ Hits           3467     3478      +11     
- Misses          467      494      +27     

Flag	Coverage Δ
unit	87.56% <0.00%> (-0.57%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chubes4]

Downstream status update for reviewer context: the generic Codebox/Homeboy path this enables is now ready on our side.

Merged downstream pieces:

• WP Codebox connector inheritance for provider plugin paths and secret env transport: Inherit connector provider plugin paths Automattic/wp-codebox#395
• Homeboy Extensions proof that Codebox task requests carry provider=codex, model=gpt-5.5, ai-provider-for-openai plugin paths, and AI_PROVIDER_OPENAI_CODEX_* secret env names without wp-ai-gateway: Prove Codebox Codex task requests Extra-Chill/homeboy-extensions#983
• Setup/operator docs clarifying Codebox minions use provider auth directly and wp-ai-gateway is only for optional external OpenCode/Kimaki endpoint mode: Clarify Codex auth and gateway setup paths Extra-Chill/wp-coding-agents#176

That leaves this PR as the remaining client-side primitive needed for WordPress/ai-provider-for-openai#28 to supply Codex request auth through the provider contract rather than an API-key bridge.

[chubes4]

Downstream dependency update:

• Add ChatGPT Codex provider ai-provider-for-openai#28 is stacked on this provider-supplied auth primitive for Codex OAuth request auth.
• Homeboy's mock Codebox/Codex fan-out proof is merged in Prove Codebox Codex task requests Extra-Chill/homeboy-extensions#983.
• WP Codebox provider plugin path inheritance is merged in Inherit connector provider plugin paths Automattic/wp-codebox#395.
• The live Codebox/Codex proof is tracked in Run live Codex proof through WP Codebox fan-out Extra-Chill/homeboy-extensions#985 and remains blocked until this PR and Add ChatGPT Codex provider ai-provider-for-openai#28 are usable in the sandbox dependency set.

[chubes4]

Downstream live proof update:

After fixing WP Codebox's status propagation in Automattic/wp-codebox#401, the Homeboy/Codebox path now correctly reports failed agent runtime outcomes instead of false success.

When rerun with WordPress/ai-provider-for-openai#28's Codex provider branch mounted, the sandbox reaches provider activation but fails because the current bundled PHP AI Client does not contain this PR's provider-auth interface:

Fatal error: Interface "WordPress\AiClient\Providers\Contracts\ProviderWithRequestAuthenticationInterface" not found

That confirms this PR is the remaining client-side primitive needed before the live Codebox/Codex minion proof can proceed. The Homeboy scheduler, extension provider dispatch, Codebox runner, provider plugin mounting, and failure evidence propagation are now all exercising the intended path.

[chubes4]

Homeboy/Codebox Codex subscription proof passed using this request-auth PR head (7afce4c09f7e1fbcfc8781074b5dff1748df5bde) together with WordPress/ai-provider-for-openai#28 at f4ada550596c1b5aff9473f9a61020a8a37fa11b.

Proof run: proof-homeboy-codex-live-overlay-20260607-003

Observed result:

• Codebox used the codex-subscription overlay profile with the live PR worktrees.
• Codex emitted structured workspace tool calls (workspace_ls, workspace_read).
• Data Machine Code executed the tool calls in the sandbox.
• workspace_read returned VERSION content 1.2.2.
• Runtime cleanup completed with runtime_status=destroyed.
• Changed files count was 0; patch bytes were 0.

This confirms the provider-supplied request-auth substrate works in the Homeboy -> WP Codebox -> Agents API/Data Machine Code Codex stack.

[felixarntz]

@chubes4 See my comment on #237 (comment), this feels a bit too much like a workaround. I think there's a cleaner solution by actually implementing a request authentication layer for bearer tokens.

Providers already have the ability to control what request authentication method they use, including the ability to wrap the passed instance at runtime (e.g. to slightly alter how the header is passed).

[chubes4]

Update after addressing the review feedback: this branch now uses a first-class bearer-token request-auth primitive rather than provider-supplied arbitrary auth.

End-to-end proof passed with the downstream Codex provider branch:

• Homeboy orchestrated the task locally and offloaded it to the homeboy-lab Linux runner.
• The runner launched a WP Codebox WordPress sandbox with the codex-subscription profile.
• The sandbox mounted this php-ai-client branch plus WordPress/ai-provider-for-openai#28.
• A native Codex-backed agent ran headlessly inside the sandbox through Agents API/Data Machine workspace tools.
• The agent made structured tool calls (workspace_ls, workspace_read) and completed successfully.
• Runtime cleanup completed; no patch/file changes were produced for the read-only proof.

Latest successful run: agent-task-b8f6e825-7f37-4d35-84f0-47927f851899.

Requesting re-review on the bearer-token auth shape.