From 14562ef19cab65533a636090871deba414be0208 Mon Sep 17 00:00:00 2001 From: Jay Fletcher <5743488+jayjfletcher@users.noreply.github.com> Date: Tue, 27 Oct 2026 00:13:38 -0400 Subject: [PATCH] Extend Keystone's Action base and a CortexException root Every action now extends RefactorCircus\Keystone\Actions\Action: callers keep execute(), each action implements a protected handle(). Every exception descends from the abstract CortexException (on Keystone's PackageException), with new Invalid{Agent,Tool,McpServer}ClassException, ImmutableVersionException and UnexpectedResultException replacing raw SPL throws. ArchTest checks both. Ported onto the ConcreteServer rename, including its new tool-override actions. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../RedirectDomainUiController.php | 4 ++-- .../CreateConcreteAgentVersionAction.php | 5 +++-- .../DeleteConcreteAgentOverrideAction.php | 5 +++-- .../ListConcreteAgentVersionsAction.php | 5 +++-- .../Actions/ListConcreteAgentsAction.php | 5 +++-- .../PublishConcreteAgentVersionAction.php | 5 +++-- .../Actions/RunConcreteAgentAction.php | 5 +++-- .../Actions/ShowConcreteAgentAction.php | 5 +++-- .../UpdateConcreteAgentToolsAction.php | 5 +++-- .../Exceptions/AgentNotFoundException.php | 6 ++++-- .../Exceptions/InvalidAgentClassException.php | 18 ++++++++++++++++++ .../ConcreteAgentOverrideVersionModel.php | 4 ++-- .../ConcreteAgent/Services/AgentRegistry.php | 6 ++---- .../ClearConcreteServerToolsAction.php | 5 +++-- .../CreateMcpInstructionVersionAction.php | 5 +++-- .../Actions/DeleteMcpInstructionAction.php | 5 +++-- .../ListMcpInstructionVersionsAction.php | 5 +++-- .../Actions/ListMcpServersAction.php | 5 +++-- .../PublishMcpInstructionVersionAction.php | 5 +++-- .../Actions/ShowMcpInstructionAction.php | 5 +++-- .../UpdateConcreteServerToolsAction.php | 5 +++-- .../InvalidMcpServerClassException.php | 18 ++++++++++++++++++ .../Exceptions/McpServerNotFoundException.php | 6 ++++-- .../Models/McpInstructionVersionModel.php | 4 ++-- .../Services/McpServerRegistry.php | 6 ++---- .../Actions/CreateRedirectDomainAction.php | 5 +++-- .../Actions/DeleteRedirectDomainAction.php | 5 +++-- .../Actions/ListRedirectDomainsAction.php | 5 +++-- .../CreateToolDescriptionVersionAction.php | 5 +++-- .../Actions/DeleteToolDescriptionAction.php | 5 +++-- .../ListToolDescriptionVersionsAction.php | 5 +++-- src/Domains/Tool/Actions/ListToolsAction.php | 5 +++-- .../PublishToolDescriptionVersionAction.php | 5 +++-- .../Actions/ShowToolDescriptionAction.php | 5 +++-- .../Exceptions/InvalidToolClassException.php | 18 ++++++++++++++++++ .../Tool/Exceptions/ToolNotFoundException.php | 6 ++++-- .../Models/ToolDescriptionVersionModel.php | 4 ++-- src/Domains/Tool/Services/ToolRegistry.php | 6 ++---- .../Actions/CreateVirtualAgentAction.php | 5 +++-- .../CreateVirtualAgentVersionAction.php | 5 +++-- .../Actions/DeleteVirtualAgentAction.php | 5 +++-- .../Actions/ListProvidersAction.php | 5 +++-- .../ListVirtualAgentVersionsAction.php | 5 +++-- .../Actions/ListVirtualAgentsAction.php | 5 +++-- .../PublishVirtualAgentVersionAction.php | 5 +++-- .../Actions/RunVirtualAgentAction.php | 5 +++-- .../Actions/ShowVirtualAgentAction.php | 5 +++-- .../Actions/ShowVirtualAgentVersionAction.php | 5 +++-- .../Actions/UpdateVirtualAgentAction.php | 5 +++-- .../CircularAgentReferenceException.php | 4 ++-- .../VirtualAgentNotPublishedException.php | 4 ++-- .../Models/VirtualAgentVersionModel.php | 4 ++-- src/Exceptions/CortexException.php | 14 ++++++++++++++ src/Exceptions/ImmutableVersionException.php | 17 +++++++++++++++++ src/Exceptions/UnexpectedResultException.php | 19 +++++++++++++++++++ tests/ArchTest.php | 17 +++++++++++++++-- tests/Feature/AgentRegistryTest.php | 3 ++- tests/Feature/Http/McpInstructionsTest.php | 3 ++- tests/Feature/Http/ToolDescriptionsTest.php | 3 ++- tests/Feature/McpServerRegistryTest.php | 3 ++- tests/Feature/ModelsTest.php | 7 ++++--- tests/Feature/ToolRegistryTest.php | 3 ++- 62 files changed, 273 insertions(+), 114 deletions(-) create mode 100644 src/Domains/ConcreteAgent/Exceptions/InvalidAgentClassException.php create mode 100644 src/Domains/ConcreteServer/Exceptions/InvalidMcpServerClassException.php create mode 100644 src/Domains/Tool/Exceptions/InvalidToolClassException.php create mode 100644 src/Exceptions/CortexException.php create mode 100644 src/Exceptions/ImmutableVersionException.php create mode 100644 src/Exceptions/UnexpectedResultException.php diff --git a/src/Atrium/Http/Controllers/RedirectDomainUiController.php b/src/Atrium/Http/Controllers/RedirectDomainUiController.php index 53c1485..9919443 100644 --- a/src/Atrium/Http/Controllers/RedirectDomainUiController.php +++ b/src/Atrium/Http/Controllers/RedirectDomainUiController.php @@ -8,7 +8,6 @@ use Illuminate\Contracts\View\View; use Illuminate\Http\RedirectResponse; use Illuminate\Http\Request; -use LogicException; use RefactorCircus\Cortex\Atrium\Http\Controllers\Concerns\AuthorizesScreens; use RefactorCircus\Cortex\Domains\RedirectDomain\Actions\CreateRedirectDomainAction; use RefactorCircus\Cortex\Domains\RedirectDomain\Actions\DeleteRedirectDomainAction; @@ -17,6 +16,7 @@ use RefactorCircus\Cortex\Domains\RedirectDomain\Data\ListRedirectDomainsData; use RefactorCircus\Cortex\Domains\RedirectDomain\Models\RedirectDomainModel; use RefactorCircus\Cortex\Domains\RedirectDomain\Services\RedirectDomains; +use RefactorCircus\Cortex\Exceptions\UnexpectedResultException; /** * Every stored redirect domain, whoever owns it. Domains added here belong @@ -121,7 +121,7 @@ private function stored(?string $source, Request $request): LengthAwarePaginator page: is_numeric($page) ? max(1, (int) $page) : null, )); - return $stored instanceof LengthAwarePaginator ? $stored->withQueryString() : throw new LogicException('A paged listing answers a page.'); + return $stored instanceof LengthAwarePaginator ? $stored->withQueryString() : throw UnexpectedResultException::pagedListing(); } /** diff --git a/src/Domains/ConcreteAgent/Actions/CreateConcreteAgentVersionAction.php b/src/Domains/ConcreteAgent/Actions/CreateConcreteAgentVersionAction.php index 321686c..92f02fc 100644 --- a/src/Domains/ConcreteAgent/Actions/CreateConcreteAgentVersionAction.php +++ b/src/Domains/ConcreteAgent/Actions/CreateConcreteAgentVersionAction.php @@ -11,12 +11,13 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class CreateConcreteAgentVersionAction +final class CreateConcreteAgentVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(string $agent, CreateConcreteAgentVersionData $data): ConcreteAgentOverrideVersionModel + protected function handle(string $agent, CreateConcreteAgentVersionData $data): ConcreteAgentOverrideVersionModel { ConcreteAgentVersionCreatingActionEvent::dispatch($agent, $data); diff --git a/src/Domains/ConcreteAgent/Actions/DeleteConcreteAgentOverrideAction.php b/src/Domains/ConcreteAgent/Actions/DeleteConcreteAgentOverrideAction.php index afe3109..0b22f1d 100644 --- a/src/Domains/ConcreteAgent/Actions/DeleteConcreteAgentOverrideAction.php +++ b/src/Domains/ConcreteAgent/Actions/DeleteConcreteAgentOverrideAction.php @@ -9,12 +9,13 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentOverrideDeletingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class DeleteConcreteAgentOverrideAction +final class DeleteConcreteAgentOverrideAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(ConcreteAgentOverrideModel $override): void + protected function handle(ConcreteAgentOverrideModel $override): void { ConcreteAgentOverrideDeletingActionEvent::dispatch($override); diff --git a/src/Domains/ConcreteAgent/Actions/ListConcreteAgentVersionsAction.php b/src/Domains/ConcreteAgent/Actions/ListConcreteAgentVersionsAction.php index 5410f38..8236ad3 100644 --- a/src/Domains/ConcreteAgent/Actions/ListConcreteAgentVersionsAction.php +++ b/src/Domains/ConcreteAgent/Actions/ListConcreteAgentVersionsAction.php @@ -9,13 +9,14 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentVersionsListingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideVersionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ListConcreteAgentVersionsAction +final class ListConcreteAgentVersionsAction extends Action { /** * @return Collection */ - public function execute(ConcreteAgentOverrideModel $override): Collection + protected function handle(ConcreteAgentOverrideModel $override): Collection { ConcreteAgentVersionsListingActionEvent::dispatch($override); diff --git a/src/Domains/ConcreteAgent/Actions/ListConcreteAgentsAction.php b/src/Domains/ConcreteAgent/Actions/ListConcreteAgentsAction.php index 806dac5..9205517 100644 --- a/src/Domains/ConcreteAgent/Actions/ListConcreteAgentsAction.php +++ b/src/Domains/ConcreteAgent/Actions/ListConcreteAgentsAction.php @@ -9,15 +9,16 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentsListingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Domains\ConcreteAgent\Services\AgentRegistry; +use RefactorCircus\Keystone\Actions\Action; -final class ListConcreteAgentsAction +final class ListConcreteAgentsAction extends Action { public function __construct(private readonly AgentRegistry $registry) {} /** * @return list, overridable: bool, tools_overridable: bool, instructions: string, tools: list, default_tools: list, override: ConcreteAgentOverrideModel|null}> */ - public function execute(): array + protected function handle(): array { ConcreteAgentsListingActionEvent::dispatch(); diff --git a/src/Domains/ConcreteAgent/Actions/PublishConcreteAgentVersionAction.php b/src/Domains/ConcreteAgent/Actions/PublishConcreteAgentVersionAction.php index 2cf9d69..b9026f5 100644 --- a/src/Domains/ConcreteAgent/Actions/PublishConcreteAgentVersionAction.php +++ b/src/Domains/ConcreteAgent/Actions/PublishConcreteAgentVersionAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class PublishConcreteAgentVersionAction +final class PublishConcreteAgentVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(ConcreteAgentOverrideModel $override, int $version): ConcreteAgentOverrideModel + protected function handle(ConcreteAgentOverrideModel $override, int $version): ConcreteAgentOverrideModel { ConcreteAgentVersionPublishingActionEvent::dispatch($override, $version); diff --git a/src/Domains/ConcreteAgent/Actions/RunConcreteAgentAction.php b/src/Domains/ConcreteAgent/Actions/RunConcreteAgentAction.php index 97050b4..d6b1dd0 100644 --- a/src/Domains/ConcreteAgent/Actions/RunConcreteAgentAction.php +++ b/src/Domains/ConcreteAgent/Actions/RunConcreteAgentAction.php @@ -9,12 +9,13 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentRanActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentRunningActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Services\AgentRegistry; +use RefactorCircus\Keystone\Actions\Action; -final class RunConcreteAgentAction +final class RunConcreteAgentAction extends Action { public function __construct(private readonly AgentRegistry $registry) {} - public function execute(string $agent, RunConcreteAgentData $data): AgentResponse + protected function handle(string $agent, RunConcreteAgentData $data): AgentResponse { ConcreteAgentRunningActionEvent::dispatch($agent, $data); diff --git a/src/Domains/ConcreteAgent/Actions/ShowConcreteAgentAction.php b/src/Domains/ConcreteAgent/Actions/ShowConcreteAgentAction.php index 358cd54..31e819f 100644 --- a/src/Domains/ConcreteAgent/Actions/ShowConcreteAgentAction.php +++ b/src/Domains/ConcreteAgent/Actions/ShowConcreteAgentAction.php @@ -9,15 +9,16 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentShownActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Domains\ConcreteAgent\Services\AgentRegistry; +use RefactorCircus\Keystone\Actions\Action; -final class ShowConcreteAgentAction +final class ShowConcreteAgentAction extends Action { public function __construct(private readonly AgentRegistry $registry) {} /** * @return array{name: string, class: class-string, overridable: bool, tools_overridable: bool, instructions: string, tools: list, default_instructions: string, default_tools: list, override: ConcreteAgentOverrideModel|null} */ - public function execute(string $agent): array + protected function handle(string $agent): array { ConcreteAgentShowingActionEvent::dispatch($agent); diff --git a/src/Domains/ConcreteAgent/Actions/UpdateConcreteAgentToolsAction.php b/src/Domains/ConcreteAgent/Actions/UpdateConcreteAgentToolsAction.php index cfaaf01..a93f338 100644 --- a/src/Domains/ConcreteAgent/Actions/UpdateConcreteAgentToolsAction.php +++ b/src/Domains/ConcreteAgent/Actions/UpdateConcreteAgentToolsAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\ConcreteAgent\Events\ConcreteAgentToolsUpdatingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteAgent\Models\ConcreteAgentOverrideModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class UpdateConcreteAgentToolsAction +final class UpdateConcreteAgentToolsAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(string $agent, UpdateConcreteAgentToolsData $data): ConcreteAgentOverrideModel + protected function handle(string $agent, UpdateConcreteAgentToolsData $data): ConcreteAgentOverrideModel { ConcreteAgentToolsUpdatingActionEvent::dispatch($agent, $data); diff --git a/src/Domains/ConcreteAgent/Exceptions/AgentNotFoundException.php b/src/Domains/ConcreteAgent/Exceptions/AgentNotFoundException.php index cd6c534..510e15e 100644 --- a/src/Domains/ConcreteAgent/Exceptions/AgentNotFoundException.php +++ b/src/Domains/ConcreteAgent/Exceptions/AgentNotFoundException.php @@ -4,10 +4,12 @@ namespace RefactorCircus\Cortex\Domains\ConcreteAgent\Exceptions; -use InvalidArgumentException; +use RefactorCircus\Cortex\Exceptions\CortexException; -final class AgentNotFoundException extends InvalidArgumentException +final class AgentNotFoundException extends CortexException { + protected int $status = 404; + public static function forName(string $name): self { return new self("Concrete agent [{$name}] is not registered."); diff --git a/src/Domains/ConcreteAgent/Exceptions/InvalidAgentClassException.php b/src/Domains/ConcreteAgent/Exceptions/InvalidAgentClassException.php new file mode 100644 index 0000000..6ffe1b1 --- /dev/null +++ b/src/Domains/ConcreteAgent/Exceptions/InvalidAgentClassException.php @@ -0,0 +1,18 @@ +loadConfigAgents(); diff --git a/src/Domains/ConcreteServer/Actions/ClearConcreteServerToolsAction.php b/src/Domains/ConcreteServer/Actions/ClearConcreteServerToolsAction.php index 822a74e..54a6b32 100644 --- a/src/Domains/ConcreteServer/Actions/ClearConcreteServerToolsAction.php +++ b/src/Domains/ConcreteServer/Actions/ClearConcreteServerToolsAction.php @@ -13,6 +13,7 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Services\McpServerRegistry; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; use Throwable; /** @@ -21,14 +22,14 @@ * the override row goes only when it holds nothing else. Clearing a server * without a tool override does nothing. */ -final class ClearConcreteServerToolsAction +final class ClearConcreteServerToolsAction extends Action { public function __construct( private readonly PublicationCache $cache, private readonly McpServerRegistry $servers, ) {} - public function execute(string $server, ClearConcreteServerToolsData $data): void + protected function handle(string $server, ClearConcreteServerToolsData $data): void { ConcreteServerToolsClearingActionEvent::dispatch($server, $data); diff --git a/src/Domains/ConcreteServer/Actions/CreateMcpInstructionVersionAction.php b/src/Domains/ConcreteServer/Actions/CreateMcpInstructionVersionAction.php index 7265482..4957845 100644 --- a/src/Domains/ConcreteServer/Actions/CreateMcpInstructionVersionAction.php +++ b/src/Domains/ConcreteServer/Actions/CreateMcpInstructionVersionAction.php @@ -11,12 +11,13 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class CreateMcpInstructionVersionAction +final class CreateMcpInstructionVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(string $server, CreateMcpInstructionVersionData $data): McpInstructionVersionModel + protected function handle(string $server, CreateMcpInstructionVersionData $data): McpInstructionVersionModel { McpInstructionVersionCreatingActionEvent::dispatch($server, $data); diff --git a/src/Domains/ConcreteServer/Actions/DeleteMcpInstructionAction.php b/src/Domains/ConcreteServer/Actions/DeleteMcpInstructionAction.php index f9a8f3b..d32e965 100644 --- a/src/Domains/ConcreteServer/Actions/DeleteMcpInstructionAction.php +++ b/src/Domains/ConcreteServer/Actions/DeleteMcpInstructionAction.php @@ -11,6 +11,7 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; use Throwable; /** @@ -22,11 +23,11 @@ * Returns the row when it survives (it still holds a tool override), or null * when it was removed, so callers can answer with what is left. */ -final class DeleteMcpInstructionAction +final class DeleteMcpInstructionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(McpInstructionModel $instruction): ?McpInstructionModel + protected function handle(McpInstructionModel $instruction): ?McpInstructionModel { McpInstructionDeletingActionEvent::dispatch($instruction); diff --git a/src/Domains/ConcreteServer/Actions/ListMcpInstructionVersionsAction.php b/src/Domains/ConcreteServer/Actions/ListMcpInstructionVersionsAction.php index 36213e9..641fb37 100644 --- a/src/Domains/ConcreteServer/Actions/ListMcpInstructionVersionsAction.php +++ b/src/Domains/ConcreteServer/Actions/ListMcpInstructionVersionsAction.php @@ -9,13 +9,14 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Events\McpInstructionVersionsListingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionVersionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ListMcpInstructionVersionsAction +final class ListMcpInstructionVersionsAction extends Action { /** * @return Collection */ - public function execute(McpInstructionModel $instruction): Collection + protected function handle(McpInstructionModel $instruction): Collection { McpInstructionVersionsListingActionEvent::dispatch($instruction); diff --git a/src/Domains/ConcreteServer/Actions/ListMcpServersAction.php b/src/Domains/ConcreteServer/Actions/ListMcpServersAction.php index bd72144..c406519 100644 --- a/src/Domains/ConcreteServer/Actions/ListMcpServersAction.php +++ b/src/Domains/ConcreteServer/Actions/ListMcpServersAction.php @@ -8,15 +8,16 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Events\McpServersListedActionEvent; use RefactorCircus\Cortex\Domains\ConcreteServer\Events\McpServersListingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteServer\Services\McpServerRegistry; +use RefactorCircus\Keystone\Actions\Action; -final class ListMcpServersAction +final class ListMcpServersAction extends Action { public function __construct(private readonly McpServerRegistry $registry) {} /** * @return list, instructions: string}> */ - public function execute(): array + protected function handle(): array { McpServersListingActionEvent::dispatch(); diff --git a/src/Domains/ConcreteServer/Actions/PublishMcpInstructionVersionAction.php b/src/Domains/ConcreteServer/Actions/PublishMcpInstructionVersionAction.php index 41fc2c3..56ead52 100644 --- a/src/Domains/ConcreteServer/Actions/PublishMcpInstructionVersionAction.php +++ b/src/Domains/ConcreteServer/Actions/PublishMcpInstructionVersionAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class PublishMcpInstructionVersionAction +final class PublishMcpInstructionVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(McpInstructionModel $instruction, int $version): McpInstructionModel + protected function handle(McpInstructionModel $instruction, int $version): McpInstructionModel { McpInstructionVersionPublishingActionEvent::dispatch($instruction, $version); diff --git a/src/Domains/ConcreteServer/Actions/ShowMcpInstructionAction.php b/src/Domains/ConcreteServer/Actions/ShowMcpInstructionAction.php index 4adb241..54c0e7e 100644 --- a/src/Domains/ConcreteServer/Actions/ShowMcpInstructionAction.php +++ b/src/Domains/ConcreteServer/Actions/ShowMcpInstructionAction.php @@ -7,10 +7,11 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Events\McpInstructionShowingActionEvent; use RefactorCircus\Cortex\Domains\ConcreteServer\Events\McpInstructionShownActionEvent; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ShowMcpInstructionAction +final class ShowMcpInstructionAction extends Action { - public function execute(string $server): McpInstructionModel + protected function handle(string $server): McpInstructionModel { McpInstructionShowingActionEvent::dispatch($server); diff --git a/src/Domains/ConcreteServer/Actions/UpdateConcreteServerToolsAction.php b/src/Domains/ConcreteServer/Actions/UpdateConcreteServerToolsAction.php index 92ce871..f509128 100644 --- a/src/Domains/ConcreteServer/Actions/UpdateConcreteServerToolsAction.php +++ b/src/Domains/ConcreteServer/Actions/UpdateConcreteServerToolsAction.php @@ -14,6 +14,7 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Services\McpServerRegistry; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; use Throwable; /** @@ -21,14 +22,14 @@ * tools, on the server's override row, creating the row when it is missing. * The `cortex` server's tools cannot be overridden. */ -final class UpdateConcreteServerToolsAction +final class UpdateConcreteServerToolsAction extends Action { public function __construct( private readonly PublicationCache $cache, private readonly McpServerRegistry $servers, ) {} - public function execute(string $server, UpdateConcreteServerToolsData $data): McpInstructionModel + protected function handle(string $server, UpdateConcreteServerToolsData $data): McpInstructionModel { ConcreteServerToolsUpdatingActionEvent::dispatch($server, $data); diff --git a/src/Domains/ConcreteServer/Exceptions/InvalidMcpServerClassException.php b/src/Domains/ConcreteServer/Exceptions/InvalidMcpServerClassException.php new file mode 100644 index 0000000..070ad40 --- /dev/null +++ b/src/Domains/ConcreteServer/Exceptions/InvalidMcpServerClassException.php @@ -0,0 +1,18 @@ +loadConfigServers(); diff --git a/src/Domains/RedirectDomain/Actions/CreateRedirectDomainAction.php b/src/Domains/RedirectDomain/Actions/CreateRedirectDomainAction.php index 607835d..0eec2fe 100644 --- a/src/Domains/RedirectDomain/Actions/CreateRedirectDomainAction.php +++ b/src/Domains/RedirectDomain/Actions/CreateRedirectDomainAction.php @@ -12,8 +12,9 @@ use RefactorCircus\Cortex\Domains\RedirectDomain\Events\RedirectDomainCreatingActionEvent; use RefactorCircus\Cortex\Domains\RedirectDomain\Models\RedirectDomainModel; use RefactorCircus\Cortex\Domains\RedirectDomain\Services\RedirectDomains; +use RefactorCircus\Keystone\Actions\Action; -final class CreateRedirectDomainAction +final class CreateRedirectDomainAction extends Action { public function __construct(private readonly RedirectDomains $domains) {} @@ -21,7 +22,7 @@ public function __construct(private readonly RedirectDomains $domains) {} * Add a domain for an owner, or for every client when there is none. * Adding one the owner already has returns it. */ - public function execute(CreateRedirectDomainData $data, ?Model $owner = null): RedirectDomainModel + protected function handle(CreateRedirectDomainData $data, ?Model $owner = null): RedirectDomainModel { RedirectDomainCreatingActionEvent::dispatch($data, $owner); diff --git a/src/Domains/RedirectDomain/Actions/DeleteRedirectDomainAction.php b/src/Domains/RedirectDomain/Actions/DeleteRedirectDomainAction.php index 12f0e8e..700def1 100644 --- a/src/Domains/RedirectDomain/Actions/DeleteRedirectDomainAction.php +++ b/src/Domains/RedirectDomain/Actions/DeleteRedirectDomainAction.php @@ -9,12 +9,13 @@ use RefactorCircus\Cortex\Domains\RedirectDomain\Events\RedirectDomainDeletingActionEvent; use RefactorCircus\Cortex\Domains\RedirectDomain\Models\RedirectDomainModel; use RefactorCircus\Cortex\Domains\RedirectDomain\Services\RedirectDomains; +use RefactorCircus\Keystone\Actions\Action; -final class DeleteRedirectDomainAction +final class DeleteRedirectDomainAction extends Action { public function __construct(private readonly RedirectDomains $domains) {} - public function execute(RedirectDomainModel $domain): void + protected function handle(RedirectDomainModel $domain): void { RedirectDomainDeletingActionEvent::dispatch($domain); diff --git a/src/Domains/RedirectDomain/Actions/ListRedirectDomainsAction.php b/src/Domains/RedirectDomain/Actions/ListRedirectDomainsAction.php index ed2122c..59edc99 100644 --- a/src/Domains/RedirectDomain/Actions/ListRedirectDomainsAction.php +++ b/src/Domains/RedirectDomain/Actions/ListRedirectDomainsAction.php @@ -12,8 +12,9 @@ use RefactorCircus\Cortex\Domains\RedirectDomain\Events\RedirectDomainsListedActionEvent; use RefactorCircus\Cortex\Domains\RedirectDomain\Events\RedirectDomainsListingActionEvent; use RefactorCircus\Cortex\Domains\RedirectDomain\Models\RedirectDomainModel; +use RefactorCircus\Keystone\Actions\Action; -final class ListRedirectDomainsAction +final class ListRedirectDomainsAction extends Action { /** * Every stored domain, or one owner's; with `paged` set, one page of @@ -21,7 +22,7 @@ final class ListRedirectDomainsAction * * @return Collection|LengthAwarePaginator */ - public function execute(?Model $owner = null, ListRedirectDomainsData $filters = new ListRedirectDomainsData): Collection|LengthAwarePaginator + protected function handle(?Model $owner = null, ListRedirectDomainsData $filters = new ListRedirectDomainsData): Collection|LengthAwarePaginator { RedirectDomainsListingActionEvent::dispatch($owner, $filters); diff --git a/src/Domains/Tool/Actions/CreateToolDescriptionVersionAction.php b/src/Domains/Tool/Actions/CreateToolDescriptionVersionAction.php index 043b26b..8fe5697 100644 --- a/src/Domains/Tool/Actions/CreateToolDescriptionVersionAction.php +++ b/src/Domains/Tool/Actions/CreateToolDescriptionVersionAction.php @@ -11,12 +11,13 @@ use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionModel; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class CreateToolDescriptionVersionAction +final class CreateToolDescriptionVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(string $tool, CreateToolDescriptionVersionData $data): ToolDescriptionVersionModel + protected function handle(string $tool, CreateToolDescriptionVersionData $data): ToolDescriptionVersionModel { ToolDescriptionVersionCreatingActionEvent::dispatch($tool, $data); diff --git a/src/Domains/Tool/Actions/DeleteToolDescriptionAction.php b/src/Domains/Tool/Actions/DeleteToolDescriptionAction.php index b2181ee..2d82ea3 100644 --- a/src/Domains/Tool/Actions/DeleteToolDescriptionAction.php +++ b/src/Domains/Tool/Actions/DeleteToolDescriptionAction.php @@ -9,12 +9,13 @@ use RefactorCircus\Cortex\Domains\Tool\Events\ToolDescriptionDeletingActionEvent; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class DeleteToolDescriptionAction +final class DeleteToolDescriptionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(ToolDescriptionModel $description): void + protected function handle(ToolDescriptionModel $description): void { ToolDescriptionDeletingActionEvent::dispatch($description); diff --git a/src/Domains/Tool/Actions/ListToolDescriptionVersionsAction.php b/src/Domains/Tool/Actions/ListToolDescriptionVersionsAction.php index d6b1c55..2e5810e 100644 --- a/src/Domains/Tool/Actions/ListToolDescriptionVersionsAction.php +++ b/src/Domains/Tool/Actions/ListToolDescriptionVersionsAction.php @@ -9,13 +9,14 @@ use RefactorCircus\Cortex\Domains\Tool\Events\ToolDescriptionVersionsListingActionEvent; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionModel; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionVersionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ListToolDescriptionVersionsAction +final class ListToolDescriptionVersionsAction extends Action { /** * @return Collection */ - public function execute(ToolDescriptionModel $description): Collection + protected function handle(ToolDescriptionModel $description): Collection { ToolDescriptionVersionsListingActionEvent::dispatch($description); diff --git a/src/Domains/Tool/Actions/ListToolsAction.php b/src/Domains/Tool/Actions/ListToolsAction.php index bfe48fc..9e20036 100644 --- a/src/Domains/Tool/Actions/ListToolsAction.php +++ b/src/Domains/Tool/Actions/ListToolsAction.php @@ -10,15 +10,16 @@ use RefactorCircus\Cortex\Domains\Tool\Events\ToolsListedActionEvent; use RefactorCircus\Cortex\Domains\Tool\Events\ToolsListingActionEvent; use RefactorCircus\Cortex\Domains\Tool\Services\ToolRegistry; +use RefactorCircus\Keystone\Actions\Action; -final class ListToolsAction +final class ListToolsAction extends Action { public function __construct(private readonly ToolRegistry $registry) {} /** * @return list|class-string, description: string, schema: array, tags: list}> */ - public function execute(ListToolsData $filters = new ListToolsData): array + protected function handle(ListToolsData $filters = new ListToolsData): array { ToolsListingActionEvent::dispatch($filters); diff --git a/src/Domains/Tool/Actions/PublishToolDescriptionVersionAction.php b/src/Domains/Tool/Actions/PublishToolDescriptionVersionAction.php index 742136c..7cf5b67 100644 --- a/src/Domains/Tool/Actions/PublishToolDescriptionVersionAction.php +++ b/src/Domains/Tool/Actions/PublishToolDescriptionVersionAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionModel; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class PublishToolDescriptionVersionAction +final class PublishToolDescriptionVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(ToolDescriptionModel $description, int $version): ToolDescriptionModel + protected function handle(ToolDescriptionModel $description, int $version): ToolDescriptionModel { ToolDescriptionVersionPublishingActionEvent::dispatch($description, $version); diff --git a/src/Domains/Tool/Actions/ShowToolDescriptionAction.php b/src/Domains/Tool/Actions/ShowToolDescriptionAction.php index 4d2d1d2..45e5fd6 100644 --- a/src/Domains/Tool/Actions/ShowToolDescriptionAction.php +++ b/src/Domains/Tool/Actions/ShowToolDescriptionAction.php @@ -7,10 +7,11 @@ use RefactorCircus\Cortex\Domains\Tool\Events\ToolDescriptionShowingActionEvent; use RefactorCircus\Cortex\Domains\Tool\Events\ToolDescriptionShownActionEvent; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ShowToolDescriptionAction +final class ShowToolDescriptionAction extends Action { - public function execute(string $tool): ToolDescriptionModel + protected function handle(string $tool): ToolDescriptionModel { ToolDescriptionShowingActionEvent::dispatch($tool); diff --git a/src/Domains/Tool/Exceptions/InvalidToolClassException.php b/src/Domains/Tool/Exceptions/InvalidToolClassException.php new file mode 100644 index 0000000..7db56da --- /dev/null +++ b/src/Domains/Tool/Exceptions/InvalidToolClassException.php @@ -0,0 +1,18 @@ +loadConfigTools(); diff --git a/src/Domains/VirtualAgent/Actions/CreateVirtualAgentAction.php b/src/Domains/VirtualAgent/Actions/CreateVirtualAgentAction.php index 1fe0882..96a27d6 100644 --- a/src/Domains/VirtualAgent/Actions/CreateVirtualAgentAction.php +++ b/src/Domains/VirtualAgent/Actions/CreateVirtualAgentAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentCreatedActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentCreatingActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; +use RefactorCircus\Keystone\Actions\Action; -final class CreateVirtualAgentAction +final class CreateVirtualAgentAction extends Action { use ResolvesVirtualAgentReferences; - public function execute(CreateVirtualAgentData $data): VirtualAgentModel + protected function handle(CreateVirtualAgentData $data): VirtualAgentModel { VirtualAgentCreatingActionEvent::dispatch($data); diff --git a/src/Domains/VirtualAgent/Actions/CreateVirtualAgentVersionAction.php b/src/Domains/VirtualAgent/Actions/CreateVirtualAgentVersionAction.php index 9164d90..5d545b8 100644 --- a/src/Domains/VirtualAgent/Actions/CreateVirtualAgentVersionAction.php +++ b/src/Domains/VirtualAgent/Actions/CreateVirtualAgentVersionAction.php @@ -11,12 +11,13 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class CreateVirtualAgentVersionAction +final class CreateVirtualAgentVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(VirtualAgentModel $agent, CreateVirtualAgentVersionData $data): VirtualAgentVersionModel + protected function handle(VirtualAgentModel $agent, CreateVirtualAgentVersionData $data): VirtualAgentVersionModel { VirtualAgentVersionCreatingActionEvent::dispatch($agent, $data); diff --git a/src/Domains/VirtualAgent/Actions/DeleteVirtualAgentAction.php b/src/Domains/VirtualAgent/Actions/DeleteVirtualAgentAction.php index 6ecdc8f..5c892f4 100644 --- a/src/Domains/VirtualAgent/Actions/DeleteVirtualAgentAction.php +++ b/src/Domains/VirtualAgent/Actions/DeleteVirtualAgentAction.php @@ -9,12 +9,13 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentDeletingActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class DeleteVirtualAgentAction +final class DeleteVirtualAgentAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(VirtualAgentModel $agent): void + protected function handle(VirtualAgentModel $agent): void { VirtualAgentDeletingActionEvent::dispatch($agent); diff --git a/src/Domains/VirtualAgent/Actions/ListProvidersAction.php b/src/Domains/VirtualAgent/Actions/ListProvidersAction.php index 9b7d1b8..5013cf8 100644 --- a/src/Domains/VirtualAgent/Actions/ListProvidersAction.php +++ b/src/Domains/VirtualAgent/Actions/ListProvidersAction.php @@ -7,9 +7,10 @@ use Laravel\Ai\AiManager; use RefactorCircus\Cortex\Domains\VirtualAgent\Events\ProvidersListedActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Events\ProvidersListingActionEvent; +use RefactorCircus\Keystone\Actions\Action; use Throwable; -final class ListProvidersAction +final class ListProvidersAction extends Action { public function __construct(private readonly AiManager $manager) {} @@ -22,7 +23,7 @@ public function __construct(private readonly AiManager $manager) {} * * @return list, default_model: string|null}> */ - public function execute(): array + protected function handle(): array { ProvidersListingActionEvent::dispatch(); diff --git a/src/Domains/VirtualAgent/Actions/ListVirtualAgentVersionsAction.php b/src/Domains/VirtualAgent/Actions/ListVirtualAgentVersionsAction.php index 29650eb..544ed5a 100644 --- a/src/Domains/VirtualAgent/Actions/ListVirtualAgentVersionsAction.php +++ b/src/Domains/VirtualAgent/Actions/ListVirtualAgentVersionsAction.php @@ -10,13 +10,14 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentVersionsListingActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentVersionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ListVirtualAgentVersionsAction +final class ListVirtualAgentVersionsAction extends Action { /** * @return LengthAwarePaginator */ - public function execute(VirtualAgentModel $agent, ListVirtualAgentVersionsData $filters = new ListVirtualAgentVersionsData): LengthAwarePaginator + protected function handle(VirtualAgentModel $agent, ListVirtualAgentVersionsData $filters = new ListVirtualAgentVersionsData): LengthAwarePaginator { VirtualAgentVersionsListingActionEvent::dispatch($agent, $filters); diff --git a/src/Domains/VirtualAgent/Actions/ListVirtualAgentsAction.php b/src/Domains/VirtualAgent/Actions/ListVirtualAgentsAction.php index 235dcde..3be375c 100644 --- a/src/Domains/VirtualAgent/Actions/ListVirtualAgentsAction.php +++ b/src/Domains/VirtualAgent/Actions/ListVirtualAgentsAction.php @@ -10,13 +10,14 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentsListedActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentsListingActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; +use RefactorCircus\Keystone\Actions\Action; -final class ListVirtualAgentsAction +final class ListVirtualAgentsAction extends Action { /** * @return LengthAwarePaginator */ - public function execute(ListVirtualAgentsData $filters = new ListVirtualAgentsData): LengthAwarePaginator + protected function handle(ListVirtualAgentsData $filters = new ListVirtualAgentsData): LengthAwarePaginator { VirtualAgentsListingActionEvent::dispatch($filters); diff --git a/src/Domains/VirtualAgent/Actions/PublishVirtualAgentVersionAction.php b/src/Domains/VirtualAgent/Actions/PublishVirtualAgentVersionAction.php index 69b44c5..55795cf 100644 --- a/src/Domains/VirtualAgent/Actions/PublishVirtualAgentVersionAction.php +++ b/src/Domains/VirtualAgent/Actions/PublishVirtualAgentVersionAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentVersionModel; use RefactorCircus\Cortex\Support\PublicationCache; +use RefactorCircus\Keystone\Actions\Action; -final class PublishVirtualAgentVersionAction +final class PublishVirtualAgentVersionAction extends Action { public function __construct(private readonly PublicationCache $cache) {} - public function execute(VirtualAgentModel $agent, int $version): VirtualAgentModel + protected function handle(VirtualAgentModel $agent, int $version): VirtualAgentModel { VirtualAgentVersionPublishingActionEvent::dispatch($agent, $version); diff --git a/src/Domains/VirtualAgent/Actions/RunVirtualAgentAction.php b/src/Domains/VirtualAgent/Actions/RunVirtualAgentAction.php index 3a76ae6..47d7726 100644 --- a/src/Domains/VirtualAgent/Actions/RunVirtualAgentAction.php +++ b/src/Domains/VirtualAgent/Actions/RunVirtualAgentAction.php @@ -10,12 +10,13 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentRunningActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Services\AgentFactory; +use RefactorCircus\Keystone\Actions\Action; -final class RunVirtualAgentAction +final class RunVirtualAgentAction extends Action { public function __construct(private readonly AgentFactory $factory) {} - public function execute(VirtualAgentModel $agent, RunVirtualAgentData $data): AgentResponse + protected function handle(VirtualAgentModel $agent, RunVirtualAgentData $data): AgentResponse { VirtualAgentRunningActionEvent::dispatch($agent, $data); diff --git a/src/Domains/VirtualAgent/Actions/ShowVirtualAgentAction.php b/src/Domains/VirtualAgent/Actions/ShowVirtualAgentAction.php index cd48bc5..6cb3efe 100644 --- a/src/Domains/VirtualAgent/Actions/ShowVirtualAgentAction.php +++ b/src/Domains/VirtualAgent/Actions/ShowVirtualAgentAction.php @@ -7,10 +7,11 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentShowingActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentShownActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; +use RefactorCircus\Keystone\Actions\Action; -final class ShowVirtualAgentAction +final class ShowVirtualAgentAction extends Action { - public function execute(VirtualAgentModel $agent): VirtualAgentModel + protected function handle(VirtualAgentModel $agent): VirtualAgentModel { VirtualAgentShowingActionEvent::dispatch($agent); diff --git a/src/Domains/VirtualAgent/Actions/ShowVirtualAgentVersionAction.php b/src/Domains/VirtualAgent/Actions/ShowVirtualAgentVersionAction.php index 916c351..c0235f3 100644 --- a/src/Domains/VirtualAgent/Actions/ShowVirtualAgentVersionAction.php +++ b/src/Domains/VirtualAgent/Actions/ShowVirtualAgentVersionAction.php @@ -8,10 +8,11 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentVersionShownActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentVersionModel; +use RefactorCircus\Keystone\Actions\Action; -final class ShowVirtualAgentVersionAction +final class ShowVirtualAgentVersionAction extends Action { - public function execute(VirtualAgentModel $agent, int $version): VirtualAgentVersionModel + protected function handle(VirtualAgentModel $agent, int $version): VirtualAgentVersionModel { VirtualAgentVersionShowingActionEvent::dispatch($agent, $version); diff --git a/src/Domains/VirtualAgent/Actions/UpdateVirtualAgentAction.php b/src/Domains/VirtualAgent/Actions/UpdateVirtualAgentAction.php index d4c0282..421a7e6 100644 --- a/src/Domains/VirtualAgent/Actions/UpdateVirtualAgentAction.php +++ b/src/Domains/VirtualAgent/Actions/UpdateVirtualAgentAction.php @@ -12,14 +12,15 @@ use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentUpdatedActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Events\VirtualAgentUpdatingActionEvent; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; +use RefactorCircus\Keystone\Actions\Action; -final class UpdateVirtualAgentAction +final class UpdateVirtualAgentAction extends Action { use ResolvesVirtualAgentReferences; public function __construct(private readonly CreateVirtualAgentVersionAction $createVersion) {} - public function execute(VirtualAgentModel $agent, UpdateVirtualAgentData $data): VirtualAgentModel + protected function handle(VirtualAgentModel $agent, UpdateVirtualAgentData $data): VirtualAgentModel { VirtualAgentUpdatingActionEvent::dispatch($agent, $data); diff --git a/src/Domains/VirtualAgent/Exceptions/CircularAgentReferenceException.php b/src/Domains/VirtualAgent/Exceptions/CircularAgentReferenceException.php index 05e51a1..7be2e60 100644 --- a/src/Domains/VirtualAgent/Exceptions/CircularAgentReferenceException.php +++ b/src/Domains/VirtualAgent/Exceptions/CircularAgentReferenceException.php @@ -5,9 +5,9 @@ namespace RefactorCircus\Cortex\Domains\VirtualAgent\Exceptions; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; -use RuntimeException; +use RefactorCircus\Cortex\Exceptions\CortexException; -final class CircularAgentReferenceException extends RuntimeException +final class CircularAgentReferenceException extends CortexException { public static function forAgent(VirtualAgentModel $agent): self { diff --git a/src/Domains/VirtualAgent/Exceptions/VirtualAgentNotPublishedException.php b/src/Domains/VirtualAgent/Exceptions/VirtualAgentNotPublishedException.php index 03fb64e..f675399 100644 --- a/src/Domains/VirtualAgent/Exceptions/VirtualAgentNotPublishedException.php +++ b/src/Domains/VirtualAgent/Exceptions/VirtualAgentNotPublishedException.php @@ -5,9 +5,9 @@ namespace RefactorCircus\Cortex\Domains\VirtualAgent\Exceptions; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; -use RuntimeException; +use RefactorCircus\Cortex\Exceptions\CortexException; -final class VirtualAgentNotPublishedException extends RuntimeException +final class VirtualAgentNotPublishedException extends CortexException { public static function forAgent(VirtualAgentModel $agent): self { diff --git a/src/Domains/VirtualAgent/Models/VirtualAgentVersionModel.php b/src/Domains/VirtualAgent/Models/VirtualAgentVersionModel.php index 2545e41..546b934 100644 --- a/src/Domains/VirtualAgent/Models/VirtualAgentVersionModel.php +++ b/src/Domains/VirtualAgent/Models/VirtualAgentVersionModel.php @@ -9,8 +9,8 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsTo; use Illuminate\Support\Carbon; -use LogicException; use RefactorCircus\Cortex\Database\Factories\VirtualAgentVersionFactory; +use RefactorCircus\Cortex\Exceptions\ImmutableVersionException; use RefactorCircus\Cortex\Support\Tables; use RefactorCircus\Keystone\Models\Concerns\DispatchesModelEvents; @@ -46,7 +46,7 @@ public function getTable(): string protected static function booted(): void { self::updating(function (): never { - throw new LogicException('Virtual agent prompt versions are immutable. Create a new version instead.'); + throw ImmutableVersionException::for('Virtual agent prompt'); }); } diff --git a/src/Exceptions/CortexException.php b/src/Exceptions/CortexException.php new file mode 100644 index 0000000..713818d --- /dev/null +++ b/src/Exceptions/CortexException.php @@ -0,0 +1,14 @@ +classes() ->toBeFinal(); +arch('actions extend the Keystone Action base: callers use execute(), the action implements a protected handle()') + ->expect(Arch::domainNamespaces('RefactorCircus\Cortex', CORTEX_DOMAINS, 'Actions')) + ->classes() + ->toExtend(Action::class); + +arch('every exception descends from CortexException') + ->expect(['RefactorCircus\Cortex\Exceptions', ...Arch::domainNamespaces('RefactorCircus\Cortex', CORTEX_DOMAINS, 'Exceptions')]) + ->classes() + ->toExtend(CortexException::class) + ->ignoring('RefactorCircus\Cortex\Exceptions\CortexException'); + arch('actions take their input as Data objects, not arrays') ->expect(fn (): array => array_values(array_filter( array_map(function (string $action): ?string { - foreach ((new ReflectionMethod($action, 'execute'))->getParameters() as $parameter) { + foreach ((new ReflectionMethod($action, 'handle'))->getParameters() as $parameter) { $type = $parameter->getType(); if ($type instanceof ReflectionNamedType && $type->getName() === 'array' && in_array($parameter->getName(), ['data', 'filters', 'input', 'attributes', 'values', 'tools'], true)) { - return $action.'::execute($'.$parameter->getName().')'; + return $action.'::handle($'.$parameter->getName().')'; } } diff --git a/tests/Feature/AgentRegistryTest.php b/tests/Feature/AgentRegistryTest.php index 7ac405b..b4aff7e 100644 --- a/tests/Feature/AgentRegistryTest.php +++ b/tests/Feature/AgentRegistryTest.php @@ -3,6 +3,7 @@ declare(strict_types=1); use RefactorCircus\Cortex\Domains\ConcreteAgent\Exceptions\AgentNotFoundException; +use RefactorCircus\Cortex\Domains\ConcreteAgent\Exceptions\InvalidAgentClassException; use RefactorCircus\Cortex\Domains\ConcreteAgent\Services\AgentRegistry; use RefactorCircus\Cortex\Tests\Fixtures\EchoAgent; use RefactorCircus\Cortex\Tests\Fixtures\EchoTool; @@ -34,7 +35,7 @@ it('rejects classes that are not agents', function () { app(AgentRegistry::class)->register('echo', EchoTool::class); -})->throws(InvalidArgumentException::class); +})->throws(InvalidAgentClassException::class); it('throws for unregistered names', function () { app(AgentRegistry::class)->get('missing'); diff --git a/tests/Feature/Http/McpInstructionsTest.php b/tests/Feature/Http/McpInstructionsTest.php index 1b3a30b..4e316fd 100644 --- a/tests/Feature/Http/McpInstructionsTest.php +++ b/tests/Feature/Http/McpInstructionsTest.php @@ -6,6 +6,7 @@ use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionVersionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Services\McpServerRegistry; +use RefactorCircus\Cortex\Exceptions\ImmutableVersionException; use RefactorCircus\Cortex\Tests\Fixtures\EchoServer; beforeEach(function () { @@ -81,7 +82,7 @@ $version = McpInstructionVersionModel::factory()->create(); $version->update(['content' => 'rewritten']); -})->throws(LogicException::class, 'immutable'); +})->throws(ImmutableVersionException::class, 'immutable'); it('serves the published override through the servers endpoint and context', function () { $this->postJson(route('cortex.servers.instructions.versions.store', ['server' => 'echo']), [ diff --git a/tests/Feature/Http/ToolDescriptionsTest.php b/tests/Feature/Http/ToolDescriptionsTest.php index 4936b1e..c6540b4 100644 --- a/tests/Feature/Http/ToolDescriptionsTest.php +++ b/tests/Feature/Http/ToolDescriptionsTest.php @@ -5,6 +5,7 @@ use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionModel; use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionVersionModel; use RefactorCircus\Cortex\Domains\Tool\Services\ToolRegistry; +use RefactorCircus\Cortex\Exceptions\ImmutableVersionException; use RefactorCircus\Cortex\Tests\Fixtures\EchoTool; beforeEach(function () { @@ -80,7 +81,7 @@ $version = ToolDescriptionVersionModel::factory()->create(); $version->update(['content' => 'rewritten']); -})->throws(LogicException::class, 'immutable'); +})->throws(ImmutableVersionException::class, 'immutable'); it('serves the published override through the tools endpoint and registry', function () { $this->postJson(route('cortex.tools.description.versions.store', ['tool' => 'echo']), [ diff --git a/tests/Feature/McpServerRegistryTest.php b/tests/Feature/McpServerRegistryTest.php index df35e3f..e8673ff 100644 --- a/tests/Feature/McpServerRegistryTest.php +++ b/tests/Feature/McpServerRegistryTest.php @@ -5,6 +5,7 @@ use RefactorCircus\Cortex\Cortex; use RefactorCircus\Cortex\Domains\ConcreteServer\Actions\ListMcpServersAction; use RefactorCircus\Cortex\Domains\ConcreteServer\ConcreteServerServiceProvider; +use RefactorCircus\Cortex\Domains\ConcreteServer\Exceptions\InvalidMcpServerClassException; use RefactorCircus\Cortex\Domains\ConcreteServer\Exceptions\McpServerNotFoundException; use RefactorCircus\Cortex\Domains\ConcreteServer\Models\McpInstructionModel; use RefactorCircus\Cortex\Domains\ConcreteServer\Services\McpServerRegistry; @@ -39,7 +40,7 @@ it('rejects classes that are not MCP servers', function () { app(McpServerRegistry::class)->register('bad', stdClass::class); -})->throws(InvalidArgumentException::class, 'must extend'); +})->throws(InvalidMcpServerClassException::class, 'must extend'); it('throws for unknown server names', function () { app(McpServerRegistry::class)->get('missing'); diff --git a/tests/Feature/ModelsTest.php b/tests/Feature/ModelsTest.php index 3e9fa8c..6e6cc2f 100644 --- a/tests/Feature/ModelsTest.php +++ b/tests/Feature/ModelsTest.php @@ -11,6 +11,7 @@ use RefactorCircus\Cortex\Domains\Tool\Models\ToolDescriptionVersionModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentModel; use RefactorCircus\Cortex\Domains\VirtualAgent\Models\VirtualAgentVersionModel; +use RefactorCircus\Cortex\Exceptions\ImmutableVersionException; it('relates virtual agents to versions and a published version', function () { $agent = VirtualAgentModel::factory()->create(); @@ -28,7 +29,7 @@ $version = VirtualAgentVersionModel::factory()->create(); $version->update(['content' => 'changed']); -})->throws(LogicException::class, 'Virtual agent prompt versions are immutable.'); +})->throws(ImmutableVersionException::class, 'Virtual agent prompt versions are immutable.'); it('enforces one version number per virtual agent', function () { $agent = VirtualAgentModel::factory()->create(); @@ -99,7 +100,7 @@ $version = McpInstructionVersionModel::factory()->create(); $version->update(['content' => 'changed']); -})->throws(LogicException::class, 'MCP server instruction versions are immutable.'); +})->throws(ImmutableVersionException::class, 'MCP server instruction versions are immutable.'); it('enforces one version number per mcp instruction', function () { $instruction = McpInstructionModel::factory()->create(); @@ -133,7 +134,7 @@ $version = ConcreteAgentOverrideVersionModel::factory()->create(); $version->update(['content' => 'changed']); -})->throws(LogicException::class, 'Concrete agent prompt versions are immutable.'); +})->throws(ImmutableVersionException::class, 'Concrete agent prompt versions are immutable.'); it('deletes versions when the concrete agent override is deleted', function () { $override = ConcreteAgentOverrideModel::factory()->create(); diff --git a/tests/Feature/ToolRegistryTest.php b/tests/Feature/ToolRegistryTest.php index f5d6e07..84078ca 100644 --- a/tests/Feature/ToolRegistryTest.php +++ b/tests/Feature/ToolRegistryTest.php @@ -5,6 +5,7 @@ use Laravel\Ai\Tools\McpServerTool; use RefactorCircus\Cortex\Cortex; use RefactorCircus\Cortex\Domains\Tool\Actions\ListToolsAction; +use RefactorCircus\Cortex\Domains\Tool\Exceptions\InvalidToolClassException; use RefactorCircus\Cortex\Domains\Tool\Exceptions\ToolNotFoundException; use RefactorCircus\Cortex\Domains\Tool\Services\ToolRegistry; use RefactorCircus\Cortex\Tests\Fixtures\EchoMcpTool; @@ -28,7 +29,7 @@ it('rejects classes that are not tools', function () { app(ToolRegistry::class)->register('bad', stdClass::class); -})->throws(InvalidArgumentException::class, 'must implement'); +})->throws(InvalidToolClassException::class, 'must implement'); it('throws for unknown tool names', function () { app(ToolRegistry::class)->get('missing');