Actions

wp_agents_api_init

Fires once per request when the AgentRegistry is first consumed. Plugins declare agent roles inside this callback; DM reconciles declarations against the datamachine_agents table on init priority 15 while Data Machine hosts the in-place Agents API substrate.

Same API DM itself uses to register the default site administrator agent. Registrations are collected statically; last-wins on slug collision so plugins can override via hook priority. The legacy datamachine_register_agents action and datamachine_register_agent() wrapper still fire while this surface lives in Data Machine, but new code should use the WordPress-shaped names.

Since: 0.99.0

add_action( 'wp_agents_api_init', function () {
    wp_register_agent( 'wiki-generator', array(
        'label'        => 'Wiki Generator',
        'description'  => 'Fetches sources, distills into wiki articles.',
        'memory_seeds' => array(
            'SOUL.md'   => MY_PLUGIN_DIR . 'agents/wiki-generator/SOUL.md',
            'MEMORY.md' => MY_PLUGIN_DIR . 'agents/wiki-generator/MEMORY.md',
        ),
    ) );
} );

See docs/core-system/agent-registration.md for the full registration contract.

datamachine_registered_agent_reconciled

Fires for each registered agent that was just materialized into the datamachine_agents table by AgentRegistry::reconcile(). Does not fire for registrations whose DB row already existed.

Since: 0.71.0

add_action( 'datamachine_registered_agent_reconciled', function ( $agent_id, $slug, $def ) {
    // One-time provisioning for newly-created agents.
}, 10, 3 );

datamachine_agent_modes

Fires once per request when the AgentModeRegistry is first consumed. Extensions register their execution modes inside this callback.

Since: 0.68.0

add_action( 'datamachine_agent_modes', function ( $modes ) {
    DataMachineEngineAIAgentModeRegistry::register( 'editor', 40, array(
        'label'       => 'Editor Agent',
        'description' => 'Content editing in the Gutenberg block editor.',
    ) );
} );

Filters

datamachine_agent_mode_{slug}

Filters the guidance text injected for a specific execution mode. Fired by AgentModeDirective at priority 22 in the directive chain.

Built-in modes with defaults: chat, pipeline, system. Unknown modes receive an empty string as the default — extension filters are the sole content source for custom modes.

Since: 0.68.0

// Append editor-specific guidance to the editor mode.
add_filter( 'datamachine_agent_mode_editor', function ( string $content, array $payload ): string {
    return $content . "nn## Editor ToolsnnYou have diff visualization tools...";
}, 10, 2 );

Return: string — The final guidance text to inject as a system message.

datamachine_memory_file_content

Filters memory file content at read time before injection into AI context. Fires for every file read by CoreMemoryFilesDirective.

Since: 0.66.0

add_filter( 'datamachine_memory_file_content', function ( string $content, string $filename, ?array $meta ): string {
    if ( 'RULES.md' === $filename ) {
        $content .= "nn## Dynamic RulenAlways greet users by name.";
    }
    return $content;
}, 10, 3 );

datamachine_resolved_memory_files

Filters the final set of memory files after MemoryPolicyResolver resolves them for a given context.

Since: 0.66.0

datamachine_oauth_can_handle_callback

Filters whether the current request is authorized to handle an OAuth callback for the given provider.

This is the primary authorization gate for OAuth callback handling. The filter fires BEFORE provider lookup, so unknown-slug requests still receive a 404 (not a 403) regardless of authorization state.

⚠️ Security Warning: Returning true from this filter authorizes the entire OAuth callback flow for this provider, which may write credentials to site/network options. Providers MUST validate authorization specific to their use case (e.g. nonce in state param, ownership of the resource being connected). Do not blanket-return true without additional provider-level checks.

⚠️ Security Warning: Returning true from this filter authorizes the entire OAuth callback flow for this provider, which may write credentials to site/network options. Providers MUST validate authorization specific to their use case (e.g. nonce in state param, ownership of the resource being connected). Do not blanket-return true without additional provider-level checks.

add_filter( 'datamachine_oauth_can_handle_callback', function ( bool $can, string $provider_slug, array $request_params ): bool {
    // Allow artist-owned Instagram OAuth callbacks.
    if ( str_starts_with( $provider_slug, 'artist-instagram-' ) ) {
        $artist_id = (int) substr( $provider_slug, strlen( 'artist-instagram-' ) );
        return ec_can_manage_artist( get_current_user_id(), $artist_id );
    }
    return $can;
}, 10, 3 );

⚠️ Security Warning: Returning true from this filter authorizes the entire OAuth callback flow for this provider, which may write credentials to site/network options. Providers MUST validate authorization specific to their use case (e.g. nonce in state param, ownership of the resource being connected). Do not blanket-return true without additional provider-level checks.

Classes

AgentModeRegistry

Since: 0.88.0

Return: bool — true to authorize, false to reject with 403.

Namespace: DataMachineEngineAI
Since: 0.68.0

AgentModeDirective

Central registry for execution modes. Extensions register modes; the settings UI and AI system consume them.

Deprecated: ContextRegistry is a class alias for AgentModeRegistry.

Class: DataMachineEngineAIDirectivesAgentModeDirective Since: 0.68.0
Priority: 22