<?php
namespace WPForms\Integrations\AI\Admin\Chat;
use Throwable;
/**
* Scope Registry — instance-based, accessed via `wpforms()->obj( 'ai_chat_scope_registry' )`.
*
* Scope classes self-register through `register( ScopeBase $scope )` from their
* own `init()`.
*
* @since 2.0.0
*/
class ScopeRegistry {
/**
* Registered scope instances, keyed by slug.
*
* @since 2.0.0
*
* @var array
*/
private $scopes = [];
/**
* Constructor.
*
* Accepts an optional pre-seeded scopes map for testing without a WPForms
* loader boot cycle.
*
* @since 2.0.0
*
* @param array $scopes Optional initial scope map.
*/
public function __construct( array $scopes = [] ) {
foreach ( $scopes as $scope ) {
$this->register( $scope );
}
}
/**
* Register a scope class instance.
*
* @since 2.0.0
*
* @param ScopeBase $scope Scope instance.
*/
public function register( ScopeBase $scope ): void {
$slug = $scope->get_slug();
if ( $slug === '' ) {
return;
}
$this->warn_on_unexpected_override( $slug, $scope );
$this->scopes[ $slug ] = $scope;
}
/**
* Log when a registration replaces a different class under the same slug.
*
* A Pro scope overriding its Lite parent under the same slug is intentional
* and stays silent (the incoming instance is a subclass of the existing one).
* An unrelated class reusing a slug is almost always a mistake, so surface it
* via the plugin log instead of letting the last writer win invisibly.
*
* @since 2.0.0
*
* @param string $slug Scope slug being registered.
* @param ScopeBase $scope Incoming scope instance.
*/
private function warn_on_unexpected_override( string $slug, ScopeBase $scope ): void {
$existing = $this->scopes[ $slug ] ?? null;
if ( $existing === null || $scope instanceof $existing ) {
return;
}
wpforms_log(
'AI Chat: scope slug collision',
[
'slug' => $slug,
'existing' => get_class( $existing ),
'incoming' => get_class( $scope ),
],
[ 'type' => 'error' ]
);
}
/**
* Get a scope instance by slug.
*
* @since 2.0.0
*
* @param string $slug Scope slug.
*
* @return ScopeBase|null
*/
public function get( string $slug ): ?ScopeBase {
return $this->scopes[ $slug ] ?? null;
}
/**
* Get all registered scope instances.
*
* @since 2.0.0
*
* @return array
*/
public function get_all(): array {
return $this->scopes;
}
/**
* Get a scope instance by slug.
*
* @since 2.0.0
*
* @param string $slug Scope slug.
*
* @return ScopeBase|null Scope instance or null when not registered.
*/
public function get_scope( string $slug ): ?ScopeBase {
return $this->get( $slug );
}
/**
* Resolve a tool call by its scope-prefixed name.
*
* Parses `<scope>__<tool>`, strips the UX-only `_label` argument, dispatches
* to the owning scope's resolver callable. Resolver exceptions are caught
* and converted to the standard error envelope.
*
* Does NOT handle the synthetic `reclassify` tool — that is detected and
* short-circuited by `Ajax\Chat::run_round_loop()` before this method is called.
*
* @since 2.0.0
*
* @param string $name Scope-prefixed tool name (e.g. `analytics__form_stats`).
* @param array $args Tool arguments. May include `_label` (stripped).
* @param array $payload Request payload (for resolver context).
*
* @return array { content: string, is_error: bool, tool_slug: string }
*/
public function resolve_tool_call( string $name, array $args, array $payload ): array {
$separator_pos = strpos( $name, '__' );
if ( $separator_pos === false ) {
return $this->format_tool_error(
'unknown_tool',
sprintf( 'Tool name "%s" is missing the scope prefix.', $name ),
'Tool names must be in the form scope_slug__tool_name.',
''
);
}
$scope_slug = substr( $name, 0, $separator_pos );
$token = substr( $name, $separator_pos + 2 );
$scope = $this->scopes[ $scope_slug ] ?? null;
if ( $scope === null ) {
return $this->format_tool_error(
'unknown_tool',
sprintf( 'Unknown scope "%s".', $scope_slug ),
'',
$scope_slug
);
}
// Defense-in-depth backstop. The tool name originates from the LLM (relayed by
// the middleware), outside the trust boundary, and is resolved against the full
// registry — so the registry must re-authorize every dispatch regardless of
// caller discipline. The Ajax handler's per-turn allow-list is the primary gate;
// this guarantees no scope executes for a user lacking its capability.
if ( ! wpforms_current_user_can( $scope->get_capability() ) ) {
return $this->format_tool_error(
'forbidden_scope',
sprintf( 'You do not have permission to use the "%s" scope.', $scope_slug ),
'',
$scope_slug
);
}
// Strip the UX-only label argument before resolver dispatch.
unset( $args['_label'] );
$callables = $scope->get_data_sources();
if ( ! isset( $callables[ $token ] ) ) {
return $this->format_tool_error(
'unknown_tool',
sprintf( 'Scope "%1$s" does not expose tool "%2$s".', $scope_slug, $token ),
'',
$scope_slug
);
}
return $this->dispatch_resolver( $callables[ $token ], $args, $payload, $scope_slug );
}
/**
* Invoke a resolver callable and wrap its result in the standard envelope.
*
* Mirrors the β `args` into the legacy `request_data.args` slot for back-compat,
* calls the resolver, and converts any thrown exception into a `resolver_failure`
* error envelope.
*
* @since 2.0.0
*
* @param callable $resolver Resolver callable for the requested token.
* @param array $args Tool arguments (already stripped of `_label`).
* @param array $payload Request payload (for resolver context).
* @param string $scope_slug Owning scope slug for the result frame.
*
* @return array [ content: string, is_error: bool, tool_slug: string ]
*/
private function dispatch_resolver( callable $resolver, array $args, array $payload, string $scope_slug ): array {
try {
$resolver_payload = $payload;
$resolver_payload['args'] = $args;
// Back-compat shim: legacy fetch methods (Analytics, FormsInventory) still
// read from $payload['request_data']['args'] — the dead α envelope. Mirror
// the β args into that slot so date_range, filters, granularity, etc. are
// not silently dropped. Remove once every fetch method reads from
// $payload['args'] directly.
$resolver_payload['request_data'] = (array) ( $resolver_payload['request_data'] ?? [] );
$resolver_payload['request_data']['args'] = $args;
// Invoke the resolver callable.
$result = $resolver( $resolver_payload );
} catch ( Throwable $e ) {
return $this->format_tool_error(
'resolver_failure',
sanitize_text_field( $e->getMessage() ),
'',
$scope_slug
);
}
return [
'content' => (string) wp_json_encode( [ 'data' => $result ] ),
'is_error' => false,
'tool_slug' => $scope_slug,
];
}
/**
* Format a tool-call error message in the standard envelope.
*
* @since 2.0.0
*
* @param string $code Machine-readable kind (e.g. `unknown_tool`).
* @param string $error Human-readable summary.
* @param string $hint Optional remedy.
* @param string $slug Scope slug for the frame (may be empty for unrouted errors).
*
* @return array Standard error envelope.
*/
private function format_tool_error( string $code, string $error, string $hint, string $slug ): array {
$payload = [
'error' => $error,
'code' => $code,
];
if ( $hint !== '' ) {
$payload['hint'] = $hint;
}
return [
'content' => (string) wp_json_encode( $payload ),
'is_error' => true,
'tool_slug' => $slug,
];
}
}