Capabilities

Agent Bridge exposes small, auditable capabilities to the Laravel Boost server and the authenticated Capell Site Agent Bridge server. Capabilities must be registered through CapellAgentBridgeCapabilityRegistry; do not expose arbitrary services or controllers as tools.

Register a Capability Provider

Packages can register a provider by tagging it with CapellAgentBridgeCapabilityProvider::class.

use Capell\AgentBridge\Contracts\CapellAgentBridgeCapabilityProvider;
use Capell\AgentBridge\Data\CapabilityData;
use Capell\AgentBridge\Enums\CapabilityRiskEnum;
use Capell\AgentBridge\Enums\CapabilityServerEnum;
use Capell\AgentBridge\Support\CapellAgentBridgeCapabilityRegistry;

final class DemoCapabilityProvider implements CapellAgentBridgeCapabilityProvider
{
    public function registerCapabilities(CapellAgentBridgeCapabilityRegistry $registry): void
    {
        $registry->register(new CapabilityData(
            key: 'demo.clear-cache',
            name: 'Clear demo cache',
            description: 'Preview or clear the demo package cache.',
            scope: 'demo.cache.write',
            server: CapabilityServerEnum::Site,
            risk: CapabilityRiskEnum::Medium,
            actionClass: ClearDemoCacheCapabilityAction::class,
            requiredPackage: 'capell-app/demo-kit',
            supportsPreview: true,
            requiresConfirmation: true,
            auditEvent: 'demo.cache.clear',
        ));
    }
}

$this->app->singleton(DemoCapabilityProvider::class);
$this->app->tag(DemoCapabilityProvider::class, CapellAgentBridgeCapabilityProvider::class);

Keys and scopes are part of the external contract. Keep them stable once a client has been issued scopes.

Write a Capability Action

Actions implement both preview() and execute(). Mutating actions should return enough preview data for a human or calling agent to see what will change before confirming.

use Capell\AgentBridge\Contracts\CapellAgentBridgeCapabilityAction;
use Capell\AgentBridge\Data\CapabilityInvocationData;
use Capell\AgentBridge\Data\CapabilityResultData;

final class ClearDemoCacheCapabilityAction implements CapellAgentBridgeCapabilityAction
{
    public function preview(CapabilityInvocationData $invocation): CapabilityResultData
    {
        return new CapabilityResultData(
            ok: true,
            message: 'Demo cache would be cleared.',
            data: [
                'cache_key' => 'capell.demo-kit',
            ],
        );
    }

    public function execute(CapabilityInvocationData $invocation): CapabilityResultData
    {
        cache()->forget('capell.demo-kit');

        return new CapabilityResultData(
            ok: true,
            message: 'Demo cache cleared.',
        );
    }
}

Keep side effects in execute(). preview() should not write.

Risk And Confirmation

CapabilityData::needsConfirmation() returns true when either requiresConfirmation is true or the risk enum requires it. Use lower risk only for read-only actions.

Field	Meaning
scope	Token scope required to see and invoke the capability.
server	Server visibility, such as Boost or authenticated Site bridge.
risk	Risk level used by confirmation rules.
requiredPackage	Optional package name checked through Capell Core before the capability is visible.
policyAbility	Optional authorization ability.
auditEvent	Event name stored by the audit action.

Config Keys

Key	Use
capell-agent-bridge.routes.*	Route registration switches. Set a route to null to stop registering it.
capell-agent-bridge.confirmation_ttl_minutes	Lifetime of confirmation tokens for mutating capabilities.
capell-agent-bridge.public_docs_paths	Documentation paths exposed to knowledge tools.
capell-agent-bridge.enable_user_resource_bridge	Adds token and bridge controls to the user admin resource.
capell-agent-bridge.home	Home route content.
capell-agent-bridge.knowledge	Knowledge server settings.

Token, confirmation, and audit table names are migration concerns. Keep them out of public setup docs unless a host app overrides storage.

Verification

vendor/bin/pest packages/agent-bridge/tests --configuration=phpunit.xml