Use runtime tool overlays for sandbox workspaces

Author: chubes4

.github/scripts/run-agent-task/execute-native-agent-task.mjs

@@ -426,7 +426,10 @@ if (execution.code === 0 && runtimeRecord.success === true && verificationPassed
   await runnerWorkspaceCore.verifyRunnerWorkspaceIntegrity(workspaceApply.integrity)
   const testPublisher = string(process.env.WP_CODEBOX_TEST_PUBLISHER_MODULE)
   const publisher = testPublisher ? (await import(pathToFileURL(resolve(testPublisher)).href)).publishRunnerWorkspace : publishRunnerWorkspace
-  publication = await publisher({ request, changedFiles: workspaceApply.changedFiles, publicationFiles: workspaceApply.publicationFiles, token: process.env.ACCESS_TOKEN || process.env.GITHUB_TOKEN })
+   const testHook = testPublisher && process.env.WP_CODEBOX_TEST_PUBLISHER_HOOK
+     ? JSON.parse(process.env.WP_CODEBOX_TEST_PUBLISHER_HOOK)
+     : undefined
+   publication = await publisher({ request, changedFiles: workspaceApply.changedFiles, publicationFiles: workspaceApply.publicationFiles, token: process.env.ACCESS_TOKEN || process.env.GITHUB_TOKEN, ...(testHook ? { testHook } : {}) })
   runtimeRecord.metadata = { ...record(runtimeRecord.metadata), runner_workspace_publication: publication }
   runtimeRecord.outputs = { ...record(runtimeRecord.outputs), runner_workspace_publication: publication }
 }

docs/agent-task-reusable-workflow.md

@@ -105,13 +105,12 @@ package file is mounted into or visible from the agent workspace.
 ## Runtime Coverage
 
 The repository's native-loop and PHP runtime-package tests execute generated
-PHP with narrow WordPress and native agent-registry
-shims. They prove digest-then-schema validation, canonical import, exact slug
-resolution, `agents/chat` selection, invocation order, and temporary-file
-cleanup. They are not a WordPress Playground end-to-end test: this repository
-does not provide a fixture that boots both the agent-registry plugin and a real
-provider-backed chat turn in Playground. The existing Playground CLI tests use
-injected CLI modules and do not exercise that plugin/provider path.
+PHP with narrow WordPress and native agent-registry shims. The non-skippable
+Playground integration additionally boots the agent registry and OpenAI
+provider path with a local HTTP interceptor. Its deterministic three-turn
+fixture reads and edits a seeded sandbox workspace, verifies provider tool
+outputs, and captures the canonical changed-files manifest and patch without
+network access or provider billing.
 
 To run the optional cross-repository package coverage, use a Docs Agent checkout
 pinned to commit `3da1b8076359db9bf9f4ee7dadcc3932c080ed71`, which contains

fixtures/agent-task-runtime-sources-run-29299109269.json

@@ -1,7 +1,7 @@
 {
   "run_id": "29299109269",
   "runtime_sources": [
-    { "version": 1, "role": "component", "repository": "automattic/agents-api", "revision": "59d1e6b473f22498e40e279130bbb4f9bcde3b73", "path": ".", "metadata": { "slug": "agents-api", "loadAs": "mu-plugin", "activate": false } },
+    { "version": 1, "role": "component", "repository": "automattic/agents-api", "revision": "fbd5641d412af76a1b8288426a577e750838b4be", "path": ".", "metadata": { "slug": "agents-api", "loadAs": "mu-plugin", "activate": false } },
     { "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" } }
   ]

packages/runtime-core/src/runner-workspace-apply.ts

@@ -114,7 +114,10 @@ function exactlyOne(refs: RunnerWorkspaceArtifactRef[], kind: string): RunnerWor
 
 async function artifactPath(root: string, value: string): Promise<string> {
   if (!value) throw new Error("Artifact reference path is required.")
-  const candidate = await realpath(isAbsolute(value) ? resolve(value) : resolve(root, value))
+  const requested = isAbsolute(value) ? resolve(value) : resolve(root, value)
+  const requestedStat = await lstat(requested)
+  if (!requestedStat.isFile() || requestedStat.isSymbolicLink()) throw new Error("Artifact must be a bounded regular file.")
+  const candidate = await realpath(requested)
   if (!pathIsWithinRoot(candidate, root)) throw new Error("Artifact reference escapes the trusted artifact root.")
   return candidate
 }

packages/wordpress-plugin/src/class-wp-codebox-agent-runtime-invoker.php

@@ -194,7 +194,7 @@ function wp_codebox_browser_runtime_execute_ability( string $ability_name, array
 return $ability->execute( $input );
 }
 
-function wp_codebox_browser_runtime_prepare_input( array $payload, array $invocation, string $session_id, array $runtime_tool_declarations, array $ability_tools, array $allowed_tool_ids, array $sandbox_tool_ids ): array {
+function wp_codebox_browser_runtime_prepare_input( array $payload, array $invocation, string $session_id, array $ability_tools, array $allowed_tool_ids, array $sandbox_tool_ids ): array {
 $agent = sanitize_key( (string) ( $payload['agent'] ?? '' ) );
 if ( '' === $agent ) {
 	$agent = 'wp-codebox-sandbox';
@@ -230,8 +230,6 @@ function wp_codebox_browser_runtime_prepare_input( array $payload, array $invoca
 		'client_name' => 'wp-codebox-browser-runner',
 		'caller_session_id' => $session_id,
 		'task_input' => $payload['task_input'] ?? array(),
-		'runtime_tools' => $runtime_tool_declarations,
-		'runtime_tool_callback' => 'wp_codebox_browser_runtime_tool_callback',
 		'ability_tools' => $ability_tools,
 	),
 );
@@ -249,7 +247,7 @@ function wp_codebox_browser_runtime_prepare_input( array $payload, array $invoca
 }
 
 $input = array_replace_recursive( $base_input, is_array( $invocation['input'] ?? null ) ? $invocation['input'] : array() );
-return function_exists( 'apply_filters' ) ? apply_filters( 'wp_codebox_browser_runtime_invocation_input', $input, $payload, $invocation, $session_id, $runtime_tool_declarations, $ability_tools, $allowed_tool_ids, $sandbox_tool_ids ) : $input;
+return function_exists( 'apply_filters' ) ? apply_filters( 'wp_codebox_browser_runtime_invocation_input', $input, $payload, $invocation, $session_id, $ability_tools, $allowed_tool_ids, $sandbox_tool_ids ) : $input;
 }
 
 function wp_codebox_browser_runtime_import_agent_bundles( array $bundle_specs ): array {

packages/wordpress-plugin/src/class-wp-codebox-browser-runner-template.php

@@ -969,44 +969,6 @@ function wp_codebox_browser_runtime_tool_name( string $tool_id ): string {
 return \'\';
 }
 
-function wp_codebox_browser_runtime_tool_declarations( array $tool_names ): array {
-global $wp_codebox_browser_artifact_environment;
-
-$declarations = array();
-foreach ( WP_Codebox_Sandbox_Workspace_Executor::tool_declarations() as $name => $declaration ) {
-	$base = substr( $name, strlen( "client/" ) );
-	if ( in_array( $base, $tool_names, true ) ) {
-		$declarations[ $base ] = $declaration;
-	}
-}
-
-$environment = is_array( $wp_codebox_browser_artifact_environment ?? null ) ? $wp_codebox_browser_artifact_environment : array();
-$root = (string) ( $environment[\'root\'] ?? \'wp-codebox-output/\' );
-$base_path = rtrim( (string) ( $environment[\'base_path\'] ?? \'/wordpress/wp-content/uploads/wp-codebox/artifacts\' ), \'/\' );
-$declarations[\'filesystem_write\'] = array(
-	\'name\'        => \'filesystem_write\',
-	\'source\'      => \'client\',
-	\'description\' => sprintf( \'Write one generated artifact file inside %s/%s. Call this once per file required by the caller artifact contract.\', $base_path, $root ),
-	\'executor\'    => \'client\',
-	\'scope\'       => \'run\',
-	\'parameters\'  => array(
-		\'type\'       => \'object\',
-		\'required\'   => array( \'path\', \'content\' ),
-		\'properties\' => array(
-			\'path\'     => array( \'type\' => \'string\', \'description\' => sprintf( \'Relative artifact path under %s, for example %sindex.html.\', $root, $root ) ),
-			\'content\'  => array( \'type\' => \'string\', \'description\' => \'Full file contents. Use UTF-8 text unless encoding is base64.\' ),
-			\'encoding\' => array( \'type\' => \'string\', \'enum\' => array( \'utf-8\', \'base64\' ) ),
-		),
-	),
-	\'runtime\'     => array(
-		\'environment\'      => \'runtime_local\',
-		\'capability_scope\' => \'runtime_local\',
-	),
-);
-
-return $declarations;
-}
-
 function wp_codebox_browser_runtime_ability_tool_declarations( array $payload ): array {
 $task_input = is_array( $payload[\'task_input\'] ?? null ) ? $payload[\'task_input\'] : array();
 $declared = is_array( $task_input[\'ability_tools\'] ?? null ) ? $task_input[\'ability_tools\'] : array();
@@ -1129,17 +1091,6 @@ function wp_codebox_browser_runtime_replay_ability_lifecycle(): array {
 }
 
 function wp_codebox_browser_runtime_tool_callback( array $request, array $payload ) {
-
-$workspace_tool = (string) ( $request[\'tool_name\'] ?? \'\' );
-if ( preg_match( "/^(?:client\\/)?workspace_(?:show|ls|read|grep|write|edit|apply_patch|git_status|git_diff)$/", $workspace_tool ) ) {
-	$task_input = is_array( $payload[\'task_input\'] ?? null ) ? $payload[\'task_input\'] : array();
-	$context = array(
-		\'workspace_root\' => \'/workspace\',
-		\'writable_paths\' => is_array( $task_input[\'writable_paths\'] ?? null ) ? $task_input[\'writable_paths\'] : array(),
-	);
-	return ( new WP_Codebox_Sandbox_Workspace_Executor() )->executeWP_Agent_Tool_Call( $request, is_array( $request[\'tool_def\'] ?? null ) ? $request[\'tool_def\'] : array(), $context );
-}
-
 if ( ! in_array( (string) ( $request[\'tool_name\'] ?? \'\' ), array( \'filesystem_write\', \'client/filesystem-write\' ), true ) ) {
 	return null;
 }

packages/wordpress-plugin/src/class-wp-codebox-runtime-package-executor.php

@@ -124,12 +124,39 @@ private function execute_workflow( array $task ): array|WP_Error {
 			$input['message'] = $this->string_value( $input['prompt'] ?? '' );
 		}
 		$input['runtime_package_task'] = $task;
+		$input['run_id']               = $this->runtime_run_id( $input );
+		$workspace_context              = $this->sandbox_workspace_context( $input );
 		$ability_object = function_exists( 'wp_get_ability' ) ? wp_get_ability( $ability ) : null;
 		if ( ! is_object( $ability_object ) || ! method_exists( $ability_object, 'execute' ) ) {
 			return new WP_Error( 'wp_codebox_runtime_package_workflow_unavailable', 'Runtime package workflow ability is unavailable.', array( 'status' => 500, 'ability' => $ability ) );
 		}
 
-		$result = $ability_object->execute( $input );
+		$runtime_tool_declarations = static function ( array $declarations, $agent, array $runtime_context ) use ( $input, $workspace_context ): array {
+			if ( ! $agent instanceof \WP_Agent || ! hash_equals( (string) $input['agent'], (string) $runtime_context['agent_slug'] ) || ! hash_equals( (string) $input['run_id'], (string) $runtime_context['run_id'] ) ) {
+				return $declarations;
+			}
+			return array_merge( $declarations, WP_Codebox_Sandbox_Workspace_Executor::tool_declarations_for_enabled_tools( $agent->get_default_config(), $workspace_context ) );
+		};
+		$tool_executors = static function ( array $executors, array $runtime_context ) use ( $input, $workspace_context ): array {
+			if ( ! hash_equals( (string) $input['agent'], (string) ( $runtime_context['agent_slug'] ?? '' ) ) || ! hash_equals( (string) $input['run_id'], (string) ( $runtime_context['run_id'] ?? '' ) ) ) {
+				return $executors;
+			}
+			$executors[ WP_Codebox_Sandbox_Workspace_Executor::TARGET_ID ] = WP_Codebox_Sandbox_Workspace_Executor::executor_for_context( $workspace_context );
+			return $executors;
+		};
+		$filters_available = function_exists( 'add_filter' ) && function_exists( 'remove_filter' );
+		if ( $filters_available ) {
+			add_filter( 'agents_api_runtime_tool_declarations', $runtime_tool_declarations, 20, 3 );
+			add_filter( 'agents_api_tool_executors', $tool_executors, 20, 2 );
+		}
+		try {
+			$result = $ability_object->execute( $input );
+		} finally {
+			if ( $filters_available ) {
+				remove_filter( 'agents_api_runtime_tool_declarations', $runtime_tool_declarations, 20 );
+				remove_filter( 'agents_api_tool_executors', $tool_executors, 20 );
+			}
+		}
 		if ( is_wp_error( $result ) ) {
 			return $result;
 		}
@@ -148,6 +175,19 @@ private function execute_workflow( array $task ): array|WP_Error {
 		return $result;
 	}
 
+	/** @param array<string,mixed> $input @return array<string,mixed> */
+	private function sandbox_workspace_context( array $input ): array {
+		$policy = is_array( $input['runner_workspace_policy'] ?? null ) ? $input['runner_workspace_policy'] : array();
+		$paths  = is_array( $policy['writable_paths'] ?? null ) ? $policy['writable_paths'] : array();
+		return array( 'workspace_root' => '/workspace', 'writable_paths' => $paths );
+	}
+
+	/** @param array<string,mixed> $input */
+	private function runtime_run_id( array $input ): string {
+		$run_id = $this->string_value( $input['run_id'] ?? '' );
+		return '' !== $run_id ? $run_id : 'wp-codebox-runtime-' . ( function_exists( 'wp_generate_uuid4' ) ? wp_generate_uuid4() : uniqid( '', true ) );
+	}
+
 	/** @param array<string,mixed> $task Runtime package task. @param array<int,array<string,mixed>> $imports Import results. @return string|WP_Error */
 	private function imported_agent_slug( array $task, array $imports ): string|WP_Error {
 		$package = is_array( $task['package'] ?? null ) ? $task['package'] : array();