Agent and ability hooks

happenboard_register_abilities

Action Free src/Service/Abilities/Bootstrap.php

Signature

do_action( 'happenboard_register_abilities' )

Example

add_action( 'happenboard_register_abilities', function () {
    \HappenBoard\Service\Abilities\Registry::ability(
        'list-sponsors',
        array(
            'namespace'     => 'acme',
            'label'         => 'List sponsors',
            'description'   => 'Returns the sponsor names attached to an event.',
            'category'      => 'happenboard-events',
            'cap'           => 'happenboard_manage_events',
            'input_schema'  => array(
                'type'       => 'object',
                'properties' => array( 'event_id' => array( 'type' => 'integer' ) ),
                'required'   => array( 'event_id' ),
            ),
            'output_schema' => array( 'type' => 'array', 'items' => array( 'type' => 'string' ) ),
            'execute'       => fn ( $input ) => acme_sponsors_for( (int) $input['event_id'] ),
        )
    );
} );

Notes

• No arguments. Both wp_register_ability() and HappenBoard’s Registry are available here.
• Registry::ability( $name, $args ) takes label, description, category, cap, execute, input_schema and output_schema, plus the optional namespace (default happenboard), write, destructive and mcp_public.
• Use your own namespace, as the example does, and one of the free plugin’s categories: happenboard-events, happenboard-booking, happenboard-attendees or happenboard-site. WordPress rejects an ability whose category does not exist.
• HappenBoard Pro registers its abilities on this action at priority 10, then fires happenboard_pro_register_abilities.

happenboard_pro_register_abilities

Action Pro src/Service/Abilities/Bootstrap.php

Signature

do_action( 'happenboard_pro_register_abilities' )

Example

add_action( 'happenboard_pro_register_abilities', function () {
    \HappenBoard\Service\Abilities\Registry::ability(
        'flag-sponsor-ticket',
        array(
            'namespace'     => 'acme',
            'label'         => 'Flag a sponsor ticket',
            'description'   => 'Marks one ticket type as a sponsor ticket.',
            'category'      => 'happenboard-commerce',
            'cap'           => 'happenboard_manage_tickets',
            'write'         => true,
            'input_schema'  => array(
                'type'       => 'object',
                'properties' => array( 'ticket_id' => array( 'type' => 'integer' ) ),
                'required'   => array( 'ticket_id' ),
            ),
            'output_schema' => array( 'type' => 'object', 'properties' => array( 'ok' => array( 'type' => 'boolean' ) ) ),
            'execute'       => fn ( $input ) => array( 'ok' => acme_flag_sponsor_ticket( (int) $input['ticket_id'] ) ),
        )
    );
} );

Notes

• No arguments. It never fires when the agent surface is off or Pro is inactive.
• The happenboard-commerce category exists only when Pro is active, so abilities in it belong on this hook.
• Set write to true for anything that changes data: the ability then uses the write budget, is announced on happenboard_ability_executed and is called with POST. Add destructive to require confirm: true.
• Pro’s own abilities use the happenboard-pro namespace. Keep yours in your own.

happenboard_ability_executed

Action Free src/Service/Abilities/Registry.php

Signature

do_action( 'happenboard_ability_executed', string $name, array $input, mixed $result, string $status )

Parameters

$name string

Full ability name, for example happenboard/create-event.

$input array<string,mixed>

The input, validated against the ability’s schema. It may contain credentials: redact it before storing it, as the agent log does.

$result mixed

What the ability returned, or the WP_Error the call was refused with.

$status string

ok, error (the ability said no, for example to a booking that is not pending), failed (an exception was caught), rate_limited, unconfirmed (a destructive call without confirm: true) or forbidden (the user lacks the capability).

Example

add_action(
    'happenboard_ability_executed',
    function ( $name, $input, $result, $status ) {
        if ( ! in_array( $status, array( 'forbidden', 'rate_limited' ), true ) ) {
            return;
        }
        error_log( sprintf(
            'Agent call %s by user %d: %s (%s)',
            $name,
            get_current_user_id(),
            $status,
            is_wp_error( $result ) ? $result->get_error_message() : ''
        ) );
    },
    10,
    4
);

Notes

• Four arguments are passed, so register with 10, 4.
• Reads never fire it. Only abilities declared with write through HappenBoard’s Registry do.
• A forbidden call fires it from the permission check, before the ability runs, once per ability per request and only for a signed-in user. $result is then a happenboard_forbidden error (HTTP 403).
• An exception thrown by a listener is caught, so it cannot turn a completed write into an error. It still stops the listeners after it, the agent log at priority 10 included.

happenboard_abuse_guard_denial_threshold

Action Free src/Service/Security/AbuseGuard.php

Signature

do_action( 'happenboard_abuse_guard_denial_threshold', int $actor_id, int $count )

Parameters

$actor_id int

ID of the signed-in user. Logged-out callers are refused before anything is counted.

$count int

Refusals in the current window: always 10, the threshold.

Example

add_action(
    'happenboard_abuse_guard_denial_threshold',
    function ( $actor_id, $count ) {
        wp_mail(
            get_option( 'admin_email' ),
            'HappenBoard: repeated agent refusals',
            sprintf( 'User %d was refused %d times in five minutes.', $actor_id, $count )
        );
    },
    10,
    2
);

Notes

• Two arguments are passed, so register with 10, 2.
• Only permission refusals count, for reads and writes alike. A request that lists the abilities, as an MCP client does for its tools, counts at most one refusal, however many abilities the user may not use. Rate-limited and unconfirmed calls do not count.
• It fires once per window. Each refusal restarts the five-minute window, so a caller who keeps trying fires it again only after five quiet minutes and ten new refusals.