php-agentic/Mcp/Tools/Agent/Phase/PhaseAddCheckpoint.php

<?php

declare(strict_types=1);

namespace Core\Mod\Agentic\Mcp\Tools\Agent\Phase;

use Core\Mod\Agentic\Models\AgentPhase;
use Core\Mod\Agentic\Models\AgentPlan;
use Core\Mod\Agentic\Mcp\Tools\Agent\AgentTool;

/**
 * Add a checkpoint note to a phase.
 */
class PhaseAddCheckpoint extends AgentTool
{
    protected string $category = 'phase';

    protected array $scopes = ['write'];

    public function name(): string
    {
        return 'phase_add_checkpoint';
    }

    public function description(): string
    {
        return 'Add a checkpoint note to a phase';
    }

    public function inputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'plan_slug' => [
                    'type' => 'string',
                    'description' => 'Plan slug identifier',
                ],
                'phase' => [
                    'type' => 'string',
                    'description' => 'Phase identifier (number or name)',
                ],
                'note' => [
                    'type' => 'string',
                    'description' => 'Checkpoint note',
                ],
                'context' => [
                    'type' => 'object',
                    'description' => 'Additional context data',
                ],
            ],
            'required' => ['plan_slug', 'phase', 'note'],
        ];
    }

    public function handle(array $args, array $context = []): array
    {
        try {
            $planSlug = $this->require($args, 'plan_slug');
            $phaseIdentifier = $this->require($args, 'phase');
            $note = $this->require($args, 'note');
        } catch (\InvalidArgumentException $e) {
            return $this->error($e->getMessage());
        }

        $plan = AgentPlan::where('slug', $planSlug)->first();

        if (! $plan) {
            return $this->error("Plan not found: {$planSlug}");
        }

        $phase = $this->findPhase($plan, $phaseIdentifier);

        if (! $phase) {
            return $this->error("Phase not found: {$phaseIdentifier}");
        }

        $phase->addCheckpoint($note, $args['context'] ?? []);

        return $this->success([
            'checkpoints' => $phase->fresh()->checkpoints,
        ]);
    }

    /**
     * Find a phase by order number or name.
     */
    protected function findPhase(AgentPlan $plan, string|int $identifier): ?AgentPhase
    {
        if (is_numeric($identifier)) {
            return $plan->agentPhases()->where('order', (int) $identifier)->first();
        }

        return $plan->agentPhases()
            ->where('name', $identifier)
            ->first();
    }
}