Use copy-on-write WP Codebox runtime (#135)

Author: chubes4

.github/workflows/README.md

@@ -12,7 +12,7 @@ The reusable workflow declares the expected typed review artifacts for Docs Agen
 
 The target repository grants `contents: write`, `pull-requests: write`, and `issues: write`. Docs Agent forwards the caller-scoped `${{ github.token }}` to WP Codebox for same-repository publication, so consumers do not configure `ACCESS_TOKEN`. `OPENAI_API_KEY` is an optional workflow secret and is required only for a live OpenAI run; skipped and dry-run calls do not require it. `EXTERNAL_PACKAGE_SOURCE_POLICY` remains a separate required v1 JSON secret. Migrate its value to the exact one-line JSON in the root README: it authorizes the selected Docs Agent package, the pinned Agents API component, the pinned PHP AI Client overlay, and the checksum-pinned OpenAI provider artifact. Both secrets are forwarded to WP Codebox without serialization into the task descriptor.
 
-Docs Agent consumes the released [WP Codebox v0.12.13](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.13) workflow and passes the matching `wp_codebox_release_ref: v0.12.13` input. WP Codebox validates that the paired tags match, resolves the release tag, verifies its package version, materializes the declared native runtime closure, and transports the native task result through controlled `.codebox` result files before publishing the workflow result. Its published OpenAI/provider-model contract is validated against the declared provider metadata, and provider artifacts retain only canonical runtime-source provenance. Before persisting workflow results or artifact uploads, WP Codebox sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. Uploads contain only allowlisted review artifacts plus the controlled workflow envelope, and lifecycle failures publish a normalized failed result even when artifact preparation cannot complete. Diagnostic messages that name runtime classes remain reviewable; PHP-shaped runtime source remains blocked even under a reviewer-safe extension. The native task request carries WP Codebox's versioned sandbox tool-policy snapshot, keeping runtime-visible tools explicit. v0.12.13 supports optional output projection descriptors and derives required artifacts from typed declarations, so a successful maintenance no-op has no required artifacts or publication output. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767), [WP Codebox #1778](https://github.com/Automattic/wp-codebox/pull/1778), and [WP Codebox #1780](https://github.com/Automattic/wp-codebox/pull/1780). Regression reference: [run `29309360438`](https://github.com/Automattic/build-with-wordpress/actions/runs/29309360438).
+Docs Agent consumes the released [WP Codebox v0.12.14](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.14) workflow and passes the matching `wp_codebox_release_ref: v0.12.14` input. WP Codebox validates that the paired tags match, resolves the release tag, verifies its package version, materializes the declared native runtime closure, and executes the selected imported package identity. It seeds a sandbox-local copy-on-write workspace and exposes the workspace tools only inside that sandbox. WP Codebox applies the returned bounded patch to the host workspace, runs validation and verification there, then publishes approved host changes. Provider artifacts retain only canonical runtime-source provenance: uploads contain allowlisted review artifacts, controlled workflow envelopes, and provenance metadata, never prepared source bytes. Before persisting workflow results or artifact uploads, WP Codebox sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. Lifecycle failures publish a normalized failed result even when artifact preparation cannot complete. Diagnostic messages that name runtime classes remain reviewable; PHP-shaped runtime source remains blocked even under a reviewer-safe extension. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767), [WP Codebox #1784](https://github.com/Automattic/wp-codebox/issues/1784), [WP Codebox #1782](https://github.com/Automattic/wp-codebox/pull/1782), and [WP Codebox #1785](https://github.com/Automattic/wp-codebox/pull/1785). Regression reference: [run `29311239264`](https://github.com/Automattic/build-with-wordpress/actions/runs/29311239264).
 
 ## Docs Agent Runner Recipe
 

.github/workflows/maintain-docs.yml

@@ -217,7 +217,7 @@ jobs:
             --argjson artifactDeclarations "$artifact_declarations" \
             '{schema:"docs-agent/runner-recipe/v1",targetRepository:$targetRepository,prompt:$prompt,docsAgent:{externalPackageSource:{repository:$repository,revision:$revision,path:$packagePath,digest:$packageDigest},agentSlug:$agentSlug},runner:{validationDependencies:$validationDependencies,verificationCommands:$verificationCommands,driftChecks:$driftChecks,writablePaths:$writablePaths,baseRef:$baseRef,docsBranch:$docsBranch,successRequiresPr:$successRequiresPr},artifacts:{expected:($artifactDeclarations|map(.name)),declarations:$artifactDeclarations}}')"
           external_package_source="$(jq -cn --arg repository "Automattic/docs-agent" --arg revision "$DOCS_AGENT_PACKAGE_REVISION" --arg path "$package_path" --arg digest "$package_digest" '{repository:$repository,revision:$revision,path:$path,digest:$digest}')"
-          runtime_sources='[{"version":1,"role":"component","repository":"Automattic/agents-api","revision":"59d1e6b473f22498e40e279130bbb4f9bcde3b73","path":".","metadata":{"slug":"agents-api","loadAs":"mu-plugin","pluginFile":"agents-api.php"}},{"version":1,"role":"provider_plugin","source":{"type":"https_zip","url":"https://downloads.wordpress.org/plugin/ai-provider-for-openai.1.0.3.zip","sha256":"48f3c0c714b3164cda79d320829830d5a0ea1116e0b19653da8af898a22d3bb6","archive_root":"ai-provider-for-openai"},"metadata":{"slug":"ai-provider-for-openai","pluginFile":"plugin.php","activate":true,"providers":["openai"]}},{"version":1,"role":"bundled_library","repository":"WordPress/php-ai-client","revision":"631704201d15ffeff7091ad3bc7156db74054956","path":".","metadata":{"library":"php-ai-client","strategy":"wordpress-scoped-bundle"}}]'
+          runtime_sources='[{"version":1,"role":"component","repository":"Automattic/agents-api","revision":"fbd5641d412af76a1b8288426a577e750838b4be","path":".","metadata":{"slug":"agents-api","loadAs":"mu-plugin","pluginFile":"agents-api.php"}},{"version":1,"role":"provider_plugin","source":{"type":"https_zip","url":"https://downloads.wordpress.org/plugin/ai-provider-for-openai.1.0.3.zip","sha256":"48f3c0c714b3164cda79d320829830d5a0ea1116e0b19653da8af898a22d3bb6","archive_root":"ai-provider-for-openai"},"metadata":{"slug":"ai-provider-for-openai","pluginFile":"plugin.php","activate":true,"providers":["openai"]}},{"version":1,"role":"bundled_library","repository":"WordPress/php-ai-client","revision":"631704201d15ffeff7091ad3bc7156db74054956","path":".","metadata":{"library":"php-ai-client","strategy":"wordpress-scoped-bundle"}}]'
 
           runner_workspace="$(jq -cn \
             --arg repo "$GITHUB_REPOSITORY_NAME" \
@@ -249,9 +249,9 @@ jobs:
       contents: write
       pull-requests: write
       issues: write
-    uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.13
+    uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.14
     with:
-      wp_codebox_release_ref: v0.12.13
+      wp_codebox_release_ref: v0.12.14
       external_package_source: ${{ needs.prepare.outputs.external_package_source }}
       runtime_sources: ${{ needs.prepare.outputs.runtime_sources }}
       workload_id: docs-agent-${{ inputs.audience }}-${{ inputs.run_kind }}

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           repository: Automattic/agents-api
-          ref: 59d1e6b473f22498e40e279130bbb4f9bcde3b73
+          ref: fbd5641d412af76a1b8288426a577e750838b4be
           path: agents-api
           token: ${{ github.token }}
           persist-credentials: false

.github/workflows/validate.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: Automattic/wp-codebox
-          ref: v0.12.13
+          ref: v0.12.14
           path: .wp-codebox
       - name: Validate Docs Agent
         env:

README.md

@@ -231,4 +231,4 @@ AGENTS_API_DIR=/path/to/agents-api php tests/native-agent-import.php
 
 It imports every native package through `wp_agent_import_runtime_bundles()`, verifies registration and preserved write-gate defaults, and invokes the default native chat handler far enough to resolve each registered agent. It intentionally fails when `AGENTS_API_DIR` is unavailable rather than treating an unexecuted importer as a passing test. It does not execute a model turn because the packages intentionally leave provider/model selection to the caller.
 
-The `Docs Agent Tests` GitHub Actions workflow runs on pull requests and pushes. It fetches Docs Agent history so it can run the immutable native package source validator, then runs the structural bundle validator, docs-link repair smoke test, and native importer integration test against `Automattic/agents-api` at `59d1e6b473f22498e40e279130bbb4f9bcde3b73`.
+The `Docs Agent Tests` GitHub Actions workflow runs on pull requests and pushes. It fetches Docs Agent history so it can run the immutable native package source validator, then runs the structural bundle validator, docs-link repair smoke test, and native importer integration test against `Automattic/agents-api` at `fbd5641d412af76a1b8288426a577e750838b4be`, the merged commit from [Agents API #425](https://github.com/Automattic/agents-api/pull/425).

tests/validate-docs-agent-bundle.php

@@ -198,11 +198,11 @@
 
 $transitional_homeboy_extensions_workflow = 'uses: Extra-Chill/homeboy-extensions/.github/workflows/runtime-agent-full-run.yml@main';
 $forbidden_docs_agent_codebox_workflow = 'uses: Automattic/wp-codebox/.github/workflows/docs-agent-runner.yml@main';
-$generic_codebox_agent_task_workflow = 'uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.13';
+$generic_codebox_agent_task_workflow = 'uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.14';
 $assert( ! str_contains( $maintain_docs_workflow, $transitional_homeboy_extensions_workflow ), 'maintain-docs.yml must not call Homeboy Extensions directly.' );
 $assert( ! str_contains( $maintain_docs_workflow, $forbidden_docs_agent_codebox_workflow ), 'maintain-docs.yml must not call a Codebox-owned Docs Agent wrapper.' );
 $assert( str_contains( $maintain_docs_workflow, $generic_codebox_agent_task_workflow ), 'maintain-docs.yml must call the generic Codebox agent-task workflow.' );
-$assert( str_contains( $maintain_docs_workflow, 'wp_codebox_release_ref: v0.12.13' ), 'maintain-docs.yml must pass the matching WP Codebox release tag.' );
+$assert( str_contains( $maintain_docs_workflow, 'wp_codebox_release_ref: v0.12.14' ), 'maintain-docs.yml must pass the matching WP Codebox release tag.' );
 
 $workflow_blocked_runtime_fragments = array_values( array_diff( $blocked_runtime_fragments, array( 'wp-codebox', 'Automattic/wp-codebox', 'OPENAI_API_KEY' ) ) );
 $workflow_internal_fragments = array_merge( $workflow_blocked_runtime_fragments, array( 'homeboy_extensions_ref:', 'runtime_ref:', 'runtime_ref }}', 'runtime_provider:', 'runtime_provider }}', 'runtime_profile:', 'runtime_profile }}', 'runtime_profiles:', 'runtime_profiles }}', 'runtime_execution:', 'runtime_execution }}', 'runtime_config:', 'runtime_config }}', 'component_contracts:', 'component_contracts }}', 'ability_requirements:', 'ability_requirements }}', 'runtime_components:', 'runtime_components }}', 'runtime_mounts:', 'runtime_mounts }}', 'required_abilities:', 'required_abilities }}', 'extra_wp_config_defines:' ) );
@@ -239,7 +239,7 @@
 foreach ( array( 'Docs Agent Runner Recipe', 'portable recipe', 'Docs Agent owns the native package' ) as $migration_note_text ) {
 	$assert( str_contains( $workflow_readme, $migration_note_text ), "Workflow README missing agent runtime note: {$migration_note_text}" );
 }
-$assert( str_contains( $workflow_readme, 'v0.12.13' ), 'Workflow README must record the WP Codebox release tag.' );
+$assert( str_contains( $workflow_readme, 'v0.12.14' ), 'Workflow README must record the WP Codebox release tag.' );
 $assert( str_contains( $workflow_readme, 'Diagnostic messages that name runtime classes remain reviewable' ), 'Workflow README must document diagnostic-versus-source detection.' );
 $assert( str_contains( $workflow_readme, 'allowlisted review artifacts' ), 'Workflow README must document the WP Codebox upload allowlist.' );
 $assert( str_contains( $workflow_readme, 'normalized failed result' ), 'Workflow README must document normalized WP Codebox failures.' );