@fleetbase/fleetops-engine 0.6.55 → 0.6.57

package/server/src/Support/Ai/Capabilities/DocsHelpCapability.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Capabilities;
+
+use Fleetbase\Ai\Models\AiTask;
+
+class DocsHelpCapability extends AbstractFleetOpsAICapability
+{
+    public function key(): string
+    {
+        return 'fleet-ops.docs_help';
+    }
+
+    public function label(): string
+    {
+        return 'Fleet-Ops docs help';
+    }
+
+    public function description(): string
+    {
+        return 'Provides curated official Fleetbase documentation references for Fleet-Ops how-to questions.';
+    }
+
+    public function resolve(AiTask $task): array
+    {
+        $prompt = $this->prompt($task);
+
+        return [
+            'references' => array_values(array_filter([
+                $this->reference('Fleet-Ops overview', 'https://fleetbase.io/docs/fleet-ops', 'Fleet-Ops capabilities, concepts, orders, resources, maintenance, connectivity, analytics, and reports.'),
+                $this->containsAny($prompt, ['order', 'dispatch', 'create']) ? $this->reference('Fleet-Ops quickstart', 'https://fleetbase.io/docs/fleet-ops/getting-started/quickstart', 'Create your first order, assign a driver, and dispatch.') : null,
+                $this->containsAny($prompt, ['driver app', 'navigator', 'mobile']) ? $this->reference('Navigator app setup', 'https://fleetbase.io/docs/fleet-ops/getting-started/navigator-app-setup', 'Set up Navigator for drivers.') : null,
+                $this->containsAny($prompt, ['maintenance', 'work order', 'parts']) ? $this->reference('Maintenance overview', 'https://fleetbase.io/docs/fleet-ops/maintenance', 'Maintenance schedules, work orders, equipment, and parts.') : null,
+                $this->containsAny($prompt, ['telematic', 'device', 'sensor', 'connectivity']) ? $this->reference('Connectivity overview', 'https://fleetbase.io/docs/fleet-ops/connectivity', 'Telematics, devices, sensors, and connectivity events.') : null,
+                $this->containsAny($prompt, ['analytics', 'report', 'reports']) ? $this->reference('Analytics overview', 'https://fleetbase.io/docs/fleet-ops/analytics', 'Fleet-Ops analytics and report workflows.') : null,
+            ])),
+        ];
+    }
+
+    protected function matchesPrompt(string $prompt): bool
+    {
+        return $this->containsAny($prompt, ['how do i', 'how to', 'docs', 'documentation', 'help me', 'where do i', 'guide']);
+    }
+
+    protected function reference(string $title, string $url, string $description): array
+    {
+        return compact('title', 'url', 'description');
+    }
+}

package/server/src/Support/Ai/Capabilities/ImportOrdersPreviewCapability.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Capabilities;
+
+use Fleetbase\Ai\Models\AiTask;
+
+class ImportOrdersPreviewCapability extends AbstractFleetOpsAICapability
+{
+    public function key(): string
+    {
+        return 'fleet-ops.import_orders_preview';
+    }
+
+    public function label(): string
+    {
+        return 'Import Fleet-Ops orders preview';
+    }
+
+    public function description(): string
+    {
+        return 'Explains and drafts preview-only Fleet-Ops import requirements for order/resource spreadsheets.';
+    }
+
+    public function type(): string
+    {
+        return 'action';
+    }
+
+    public function mode(): string
+    {
+        return 'preview';
+    }
+
+    public function permissions(): array
+    {
+        return ['fleet-ops import order'];
+    }
+
+    public function resolve(AiTask $task): array
+    {
+        return [
+            'preview_only'     => true,
+            'action'           => 'import_orders',
+            'authorized'       => $this->can('fleet-ops import order'),
+            'message'          => 'This pilot can inspect intent and explain import requirements, but it will not process uploaded spreadsheets.',
+            'accepted_sources' => ['xlsx', 'csv'],
+            'minimum_columns'  => [
+                'pickup address or pickup place',
+                'dropoff address or dropoff place',
+                'customer/contact reference',
+                'order type/configuration when required',
+                'item/entity details when required',
+            ],
+            'draft_hints'      => [
+                'Ask the user to upload a spreadsheet through the Fleet-Ops import flow.',
+                'Do not claim rows were imported.',
+                'Offer to summarize expected columns or validation issues once file inspection support exists.',
+            ],
+        ];
+    }
+
+    protected function matchesPrompt(string $prompt): bool
+    {
+        return $this->containsAny($prompt, ['import', 'spreadsheet', 'excel', 'xlsx', 'csv']) && $this->containsAny($prompt, ['order', 'orders', 'resources', 'vehicles', 'drivers']);
+    }
+}

package/server/src/Support/Ai/Capabilities/OperationalQueryCapability.php

@@ -0,0 +1,319 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Capabilities;
+
+use Fleetbase\Ai\Models\AiTask;
+use Fleetbase\Ai\Services\AiQueryExecutor;
+use Fleetbase\Ai\Support\AiRelativeDateResolver;
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\ServiceArea;
+use Fleetbase\FleetOps\Models\Zone;
+use Illuminate\Database\Eloquent\Builder;
+
+class OperationalQueryCapability extends AbstractFleetOpsAICapability
+{
+    public function key(): string
+    {
+        return 'fleet-ops.operational_query';
+    }
+
+    public function label(): string
+    {
+        return 'Fleet-Ops operational query';
+    }
+
+    public function description(): string
+    {
+        return 'Executes safe allowlisted Fleet-Ops operational queries and aggregate summaries.';
+    }
+
+    public function permissions(): array
+    {
+        return [
+            'fleet-ops list driver',
+            'fleet-ops list vehicle',
+            'fleet-ops list device',
+            'fleet-ops list order',
+            'fleet-ops list fleet',
+            'fleet-ops list service-area',
+            'fleet-ops list zone',
+        ];
+    }
+
+    public function resolve(AiTask $task): array
+    {
+        $prompt   = $this->prompt($task);
+        $executor = app(AiQueryExecutor::class);
+        $queries  = [];
+
+        if ($this->mentions($prompt, ['driver', 'drivers'])) {
+            $queries['drivers'] = $this->driverQueries($prompt, $executor);
+        }
+
+        if ($this->mentions($prompt, ['vehicle', 'vehicles'])) {
+            $queries['vehicles'] = $this->onlineResourceQueries('fleet-ops.vehicles', $prompt, $executor);
+        }
+
+        if ($this->mentions($prompt, ['device', 'devices'])) {
+            $queries['devices'] = $this->onlineResourceQueries('fleet-ops.devices', $prompt, $executor);
+        }
+
+        if ($this->mentions($prompt, ['order', 'orders'])) {
+            $queries['orders'] = $this->orderQueries($prompt, $executor);
+        }
+
+        if ($this->mentions($prompt, ['fleet', 'fleets'])) {
+            $queries['fleets'] = [
+                'total' => $executor->count('fleet-ops.fleets'),
+            ];
+        }
+
+        return [
+            'authorized'   => true,
+            'query_engine' => 'fleetbase_ai_allowlisted_operational_query',
+            'instruction'  => 'Answer only from these executed Fleetbase query summaries. If a requested metric is missing or empty, say that Fleetbase did not return enough data for that specific metric.',
+            'queries'      => array_filter($queries),
+        ];
+    }
+
+    protected function matchesPrompt(string $prompt): bool
+    {
+        return $this->mentions($prompt, ['driver', 'drivers', 'vehicle', 'vehicles', 'device', 'devices', 'order', 'orders', 'fleet', 'fleets'])
+            && $this->mentions($prompt, ['how many', 'count', 'where', 'located', 'location', 'majority', 'online', 'offline', 'without', 'unassigned', 'assigned', 'break down', 'status', 'service area', 'zone', 'today', 'yesterday', 'tomorrow', 'this week', 'last week', 'next week', 'this month', 'last month', 'last 30 days']);
+    }
+
+    protected function driverQueries(string $prompt, AiQueryExecutor $executor): array
+    {
+        $dateWindow  = $this->dateWindow($prompt);
+        $dateFilters = $dateWindow ? $this->dateFilters($dateWindow, 'updated_at') : [];
+
+        $queries = [
+            'total'            => $executor->count('fleet-ops.drivers'),
+            'online'           => $executor->count('fleet-ops.drivers', [['field' => 'online', 'operator' => '=', 'value' => true]]),
+            'offline'          => $executor->count('fleet-ops.drivers', [['field' => 'online', 'operator' => 'false_or_null']]),
+            'counts_by_status' => $executor->countsBy('fleet-ops.drivers', 'status'),
+        ];
+
+        if ($dateWindow) {
+            $queries['date_window']       = $this->dateWindowPayload($dateWindow, 'updated_at');
+            $queries['total_in_window']   = $executor->count('fleet-ops.drivers', $dateFilters);
+            $queries['online_in_window']  = $executor->count('fleet-ops.drivers', array_merge($dateFilters, [['field' => 'online', 'operator' => '=', 'value' => true]]));
+            $queries['offline_in_window'] = $executor->count('fleet-ops.drivers', array_merge($dateFilters, [['field' => 'online', 'operator' => 'false_or_null']]));
+        }
+
+        if ($this->mentions($prompt, ['without vehicle', 'without vehicles', 'unassigned vehicle', 'no vehicle'])) {
+            $queries['without_vehicle'] = [
+                'count'   => $executor->count('fleet-ops.drivers', [['field' => 'vehicle_uuid', 'operator' => 'null']]),
+                'samples' => $executor->samples('fleet-ops.drivers', [['field' => 'vehicle_uuid', 'operator' => 'null']], 10),
+            ];
+        }
+
+        if ($this->mentions($prompt, ['where', 'located', 'location', 'majority', 'service area', 'zone'])) {
+            $filters = array_merge($dateFilters, $this->mentions($prompt, ['online']) ? [['field' => 'online', 'operator' => '=', 'value' => true]] : []);
+
+            $queries['location_summary']          = $executor->locationSummary('fleet-ops.drivers', $filters, 250);
+            $queries['service_area_distribution'] = $this->driverGeofenceDistribution($filters);
+        }
+
+        return $queries;
+    }
+
+    protected function onlineResourceQueries(string $resource, string $prompt, AiQueryExecutor $executor): array
+    {
+        $dateWindow  = $this->dateWindow($prompt);
+        $dateField   = $resource === 'fleet-ops.devices' ? 'last_online_at' : 'updated_at';
+        $dateFilters = $dateWindow ? $this->dateFilters($dateWindow, $dateField) : [];
+
+        $queries = [
+            'total'            => $executor->count($resource),
+            'online'           => $executor->count($resource, [['field' => 'online', 'operator' => '=', 'value' => true]]),
+            'offline'          => $executor->count($resource, [['field' => 'online', 'operator' => 'false_or_null']]),
+            'counts_by_status' => $executor->countsBy($resource, 'status'),
+        ];
+
+        if ($dateWindow) {
+            $queries['date_window']       = $this->dateWindowPayload($dateWindow, $dateField);
+            $queries['total_in_window']   = $executor->count($resource, $dateFilters);
+            $queries['online_in_window']  = $executor->count($resource, array_merge($dateFilters, [['field' => 'online', 'operator' => '=', 'value' => true]]));
+            $queries['offline_in_window'] = $executor->count($resource, array_merge($dateFilters, [['field' => 'online', 'operator' => 'false_or_null']]));
+        }
+
+        if ($this->mentions($prompt, ['where', 'located', 'location', 'majority']) && $resource === 'fleet-ops.vehicles') {
+            $queries['location_summary'] = $executor->locationSummary($resource, array_merge($dateFilters, $this->mentions($prompt, ['online']) ? [['field' => 'online', 'operator' => '=', 'value' => true]] : []), 250);
+        }
+
+        return $queries;
+    }
+
+    protected function orderQueries(string $prompt, AiQueryExecutor $executor): array
+    {
+        $filters = $this->orderDateFilters($prompt);
+
+        if ($this->mentions($prompt, ['active'])) {
+            $filters[] = ['field' => 'status', 'operator' => 'not_in', 'value' => ['canceled', 'completed', 'expired']];
+        }
+
+        $queries = [
+            'total'            => $executor->count('fleet-ops.orders', $filters),
+            'counts_by_status' => $executor->countsBy('fleet-ops.orders', 'status', $filters),
+        ];
+
+        if ($dateWindow = $this->dateWindow($prompt)) {
+            $queries['date_window'] = $this->dateWindowPayload($dateWindow, 'created_at');
+        }
+
+        if ($this->mentions($prompt, ['without driver', 'unassigned driver', 'no driver'])) {
+            $queries['without_driver'] = $executor->count('fleet-ops.orders', array_merge($filters, [['field' => 'driver_assigned_uuid', 'operator' => 'null']]));
+        }
+
+        if ($this->mentions($prompt, ['assigned driver', 'with driver'])) {
+            $queries['with_driver'] = $executor->count('fleet-ops.orders', array_merge($filters, [['field' => 'driver_assigned_uuid', 'operator' => 'not_null']]));
+        }
+
+        if ($this->mentions($prompt, ['without vehicle', 'unassigned vehicle', 'no vehicle'])) {
+            $queries['without_vehicle'] = $executor->count('fleet-ops.orders', array_merge($filters, [['field' => 'vehicle_assigned_uuid', 'operator' => 'null']]));
+        }
+
+        return $queries;
+    }
+
+    protected function driverGeofenceDistribution(array $filters = []): array
+    {
+        if (!$this->can('fleet-ops list driver')) {
+            return ['authorized' => false, 'resource' => 'fleet-ops.drivers'];
+        }
+
+        $query = Driver::where('company_uuid', session('company'))
+            ->applyDirectivesForPermissions('fleet-ops list driver');
+
+        foreach ($filters as $filter) {
+            if (($filter['field'] ?? null) === 'online') {
+                $query->where('online', (bool) ($filter['value'] ?? false));
+            }
+
+            if (($filter['field'] ?? null) === 'updated_at' && in_array($filter['operator'] ?? null, ['>=', '<='], true)) {
+                $query->where('updated_at', $filter['operator'], $filter['value']);
+            }
+        }
+
+        $drivers = $this->whereValidDriverLocation($query)
+            ->latest()
+            ->limit(250)
+            ->get(['uuid', 'public_id', 'company_uuid', 'location', 'city', 'country', 'online']);
+
+        if ($drivers->isEmpty()) {
+            return [
+                'authorized'           => true,
+                'valid_location_count' => 0,
+                'service_areas'        => [],
+                'zones'                => [],
+            ];
+        }
+
+        $serviceAreaCounts = [];
+        $zoneCounts        = [];
+
+        foreach ($drivers as $driver) {
+            $point = $driver->location;
+            if (!is_object($point) || !method_exists($point, 'getLat') || !method_exists($point, 'getLng')) {
+                continue;
+            }
+
+            $wkt = sprintf('POINT(%s %s)', $point->getLng(), $point->getLat());
+
+            if ($this->can('fleet-ops list service-area')) {
+                ServiceArea::where('company_uuid', session('company'))
+                    ->whereNotNull('border')
+                    ->whereRaw('MBRContains(`border`, ST_GeomFromText(?))', [$wkt])
+                    ->whereRaw('ST_Contains(`border`, ST_GeomFromText(?))', [$wkt])
+                    ->get(['uuid', 'name', 'public_id'])
+                    ->each(function (ServiceArea $serviceArea) use (&$serviceAreaCounts) {
+                        $key = $serviceArea->uuid;
+                        $serviceAreaCounts[$key] ??= [
+                            'uuid'      => $serviceArea->uuid,
+                            'public_id' => $serviceArea->public_id,
+                            'name'      => $serviceArea->name,
+                            'count'     => 0,
+                        ];
+                        $serviceAreaCounts[$key]['count']++;
+                    });
+            }
+
+            if ($this->can('fleet-ops list zone')) {
+                Zone::where('company_uuid', session('company'))
+                    ->whereNotNull('border')
+                    ->whereRaw('MBRContains(`border`, ST_GeomFromText(?))', [$wkt])
+                    ->whereRaw('ST_Contains(`border`, ST_GeomFromText(?))', [$wkt])
+                    ->get(['uuid', 'name', 'public_id', 'service_area_uuid'])
+                    ->each(function (Zone $zone) use (&$zoneCounts) {
+                        $key = $zone->uuid;
+                        $zoneCounts[$key] ??= [
+                            'uuid'              => $zone->uuid,
+                            'public_id'         => $zone->public_id,
+                            'name'              => $zone->name,
+                            'service_area_uuid' => $zone->service_area_uuid,
+                            'count'             => 0,
+                        ];
+                        $zoneCounts[$key]['count']++;
+                    });
+            }
+        }
+
+        return [
+            'authorized'           => true,
+            'valid_location_count' => $drivers->count(),
+            'service_areas'        => collect($serviceAreaCounts)->sortByDesc('count')->take(10)->values()->all(),
+            'zones'                => collect($zoneCounts)->sortByDesc('count')->take(10)->values()->all(),
+        ];
+    }
+
+    protected function whereValidDriverLocation(Builder $query): Builder
+    {
+        return $query->whereNotNull('location')->whereRaw('
+            ST_Y(location) BETWEEN -90 AND 90
+            AND ST_X(location) BETWEEN -180 AND 180
+            AND NOT (ST_X(location) = 0 AND ST_Y(location) = 0)
+        ');
+    }
+
+    protected function orderDateFilters(string $prompt): array
+    {
+        $window = $this->dateWindow($prompt);
+
+        return $window ? $this->dateFilters($window, 'created_at') : [];
+    }
+
+    protected function dateWindow(string $prompt): ?array
+    {
+        return $this->relativeDateResolver()->resolveWindow($prompt);
+    }
+
+    protected function dateFilters(array $window, string $field): array
+    {
+        return [
+            ['field' => $field, 'operator' => '>=', 'value' => $window['start']],
+            ['field' => $field, 'operator' => '<=', 'value' => $window['end']],
+        ];
+    }
+
+    protected function dateWindowPayload(array $window, string $field): array
+    {
+        return [
+            'label'    => $window['label'],
+            'timezone' => $window['timezone'],
+            'field'    => $field,
+            'start'    => $window['start']->toIso8601String(),
+            'end'      => $window['end']->toIso8601String(),
+        ];
+    }
+
+    protected function relativeDateResolver(): AiRelativeDateResolver
+    {
+        return function_exists('app') ? app(AiRelativeDateResolver::class) : new AiRelativeDateResolver(null);
+    }
+
+    protected function mentions(string $prompt, array $terms): bool
+    {
+        return $this->containsAny($prompt, $terms);
+    }
+}

package/server/src/Support/Ai/Capabilities/OptimizeOrderRouteCapability.php

@@ -0,0 +1,240 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Capabilities;
+
+use Fleetbase\Ai\Contracts\AIActionCapabilityInterface;
+use Fleetbase\Ai\Models\AiTask;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Place;
+use Illuminate\Support\Facades\DB;
+
+class OptimizeOrderRouteCapability extends AbstractFleetOpsAICapability implements AIActionCapabilityInterface
+{
+    public function key(): string
+    {
+        return 'fleet-ops.optimize_order_route';
+    }
+
+    public function label(): string
+    {
+        return 'Optimize Fleet-Ops order route';
+    }
+
+    public function description(): string
+    {
+        return 'Previews and applies confirmed waypoint resequencing for a Fleet-Ops order route.';
+    }
+
+    public function type(): string
+    {
+        return 'action';
+    }
+
+    public function mode(): string
+    {
+        return 'confirmation_required';
+    }
+
+    public function permissions(): array
+    {
+        return ['fleet-ops optimize order', 'fleet-ops update-route-for order'];
+    }
+
+    public function previewOnly(): bool
+    {
+        return false;
+    }
+
+    public function executable(): bool
+    {
+        return true;
+    }
+
+    public function inputSchema(): array
+    {
+        return [
+            'order'     => 'Fleet-Ops order UUID or public ID.',
+            'waypoints' => 'Ordered waypoint place UUIDs generated by the preview.',
+        ];
+    }
+
+    public function shouldPreview(AiTask $task): bool
+    {
+        return $this->matchesPrompt($this->prompt($task));
+    }
+
+    public function resolve(AiTask $task): array
+    {
+        return $this->preview($task);
+    }
+
+    public function preview(AiTask $task, array $input = []): array
+    {
+        $authorized = $this->canAll($this->permissions());
+        $orders     = $this->resolveOrders($task);
+
+        if ($orders->count() > 1) {
+            return [
+                'action'         => $this->key(),
+                'authorized'     => $authorized,
+                'ready'          => false,
+                'preview_only'   => true,
+                'message'        => 'Fleetbase AI found multiple orders. Multi-order route sequencing should use the Fleet-Ops Orchestrator preview before commit.',
+                'apply_label'    => 'Open Orchestrator',
+                'cancel_label'   => 'Cancel',
+                'missing_fields' => ['single order selection for direct route apply'],
+                'fields'         => $orders->map(fn (Order $order) => ['label' => 'Order', 'value' => $order->public_id ?: $order->uuid])->values()->all(),
+                'draft'          => ['orders' => $orders->pluck('public_id')->filter()->values()->all(), 'mode' => 'optimize_routes'],
+                'risks'          => ['Multi-order optimization can affect manifests and should be committed through Orchestrator review.'],
+            ];
+        }
+
+        $order = $orders->first();
+        if (!$order) {
+            return [
+                'action'         => $this->key(),
+                'authorized'     => $authorized,
+                'ready'          => false,
+                'message'        => 'Fleetbase AI needs a specific Fleet-Ops order ID before it can optimize a route.',
+                'apply_label'    => 'Optimize route',
+                'cancel_label'   => 'Cancel',
+                'missing_fields' => ['order UUID or public ID'],
+                'fields'         => [],
+                'draft'          => [],
+            ];
+        }
+
+        $order->loadMissing(['payload.pickup', 'payload.dropoff', 'payload.waypoints.place']);
+        $waypoints = $order->payload?->waypoints?->sortBy('order')->values() ?? collect();
+        $optimized = $this->optimizeWaypoints($order, $waypoints);
+        $changed   = $waypoints->pluck('place_uuid')->values()->all() !== $optimized->pluck('place_uuid')->values()->all();
+        $missing   = array_values(array_filter([
+            $authorized ? null : 'permission to optimize and update Fleet-Ops order routes',
+            $waypoints->count() >= 2 ? null : 'at least two route waypoints',
+            $changed ? null : 'a route with a different optimized waypoint sequence',
+        ]));
+
+        return [
+            'action'         => $this->key(),
+            'authorized'     => $authorized,
+            'ready'          => empty($missing),
+            'message'        => empty($missing) ? 'Fleetbase AI prepared an optimized waypoint sequence. Review it before applying.' : 'Fleetbase AI cannot apply a route optimization until the route has optimizable waypoints.',
+            'apply_label'    => 'Apply route',
+            'cancel_label'   => 'Cancel',
+            'missing_fields' => $missing,
+            'fields'         => [
+                ['label' => 'Order', 'value' => $order->public_id ?: $order->uuid],
+                ['label' => 'Current sequence', 'value' => $this->stopLabels($waypoints)->implode(' -> ')],
+                ['label' => 'Proposed sequence', 'value' => $this->stopLabels($optimized)->implode(' -> ')],
+            ],
+            'draft'          => [
+                'order_uuid' => $order->uuid,
+                'waypoints'  => $optimized->values()->map(fn ($waypoint, int $index) => [
+                    'place_uuid' => $waypoint->place_uuid,
+                    'order'      => $index,
+                    'type'       => $waypoint->type ?: 'dropoff',
+                ])->all(),
+            ],
+            'risks'          => ['Applying this changes the order waypoint sequence only after confirmation.'],
+        ];
+    }
+
+    public function apply(AiTask $task, array $preview = [], array $input = []): array
+    {
+        if (!$this->canAll($this->permissions())) {
+            throw new \RuntimeException('You do not have permission to optimize Fleet-Ops order routes.');
+        }
+
+        if (!data_get($preview, 'ready')) {
+            throw new \RuntimeException('This route optimization preview is not ready to apply.');
+        }
+
+        $order = Order::where('company_uuid', session('company'))
+            ->where('uuid', data_get($preview, 'draft.order_uuid'))
+            ->with(['payload'])
+            ->first();
+
+        if (!$order || !$order->payload) {
+            throw new \RuntimeException('Unable to find the Fleet-Ops order route to update.');
+        }
+
+        $waypoints = array_values((array) data_get($preview, 'draft.waypoints', []));
+        if (count($waypoints) < 2) {
+            throw new \RuntimeException('The route optimization preview does not include enough waypoints to apply.');
+        }
+
+        DB::transaction(function () use ($order, $waypoints) {
+            $order->payload->updateWaypoints($waypoints);
+            $order->is_route_optimized = true;
+            $order->save();
+        });
+
+        return [
+            'action'   => $this->key(),
+            'status'   => 'completed',
+            'message'  => 'Fleet-Ops order route was optimized.',
+            'resource' => [
+                'type'   => 'order',
+                'id'     => $order->public_id,
+                'uuid'   => $order->uuid,
+                'route'  => 'console.fleet-ops.operations.orders.index.details',
+                'models' => array_filter([$order->public_id ?: $order->uuid]),
+            ],
+        ];
+    }
+
+    protected function matchesPrompt(string $prompt): bool
+    {
+        return str_contains($prompt, 'order') && $this->containsAny($prompt, ['optimize route', 'optimise route', 'route optimization', 'route optimisation', 'optimize the route', 'optimise the route']);
+    }
+
+    protected function resolveOrders(AiTask $task)
+    {
+        $terms = $this->searchTerms((string) $task->prompt);
+
+        return Order::where('company_uuid', session('company'))
+            ->where(function ($query) use ($terms) {
+                $this->whereLikeAny($query, ['uuid', 'public_id', 'internal_id'], $terms);
+            })
+            ->with(['payload.pickup', 'payload.dropoff', 'payload.waypoints.place'])
+            ->limit(10)
+            ->get();
+    }
+
+    protected function optimizeWaypoints(Order $order, $waypoints)
+    {
+        if ($waypoints->count() < 2) {
+            return $waypoints;
+        }
+
+        $remaining = $waypoints->values();
+        $optimized = collect();
+        $cursor    = $order->payload?->pickup;
+
+        while ($remaining->isNotEmpty()) {
+            $nearest = $remaining
+                ->sortBy(fn ($waypoint) => $this->distance($cursor, $waypoint->place))
+                ->first();
+
+            $optimized->push($nearest);
+            $remaining = $remaining->reject(fn ($waypoint) => $waypoint->uuid === $nearest->uuid)->values();
+            $cursor    = $nearest->place;
+        }
+
+        return $optimized;
+    }
+
+    protected function distance(?Place $from, ?Place $to): float
+    {
+        if (!$from || !$to || !is_numeric($from->lat) || !is_numeric($from->lng) || !is_numeric($to->lat) || !is_numeric($to->lng)) {
+            return PHP_FLOAT_MAX;
+        }
+
+        return sqrt((float) (($from->lat - $to->lat) ** 2 + ($from->lng - $to->lng) ** 2));
+    }
+
+    protected function stopLabels($waypoints)
+    {
+        return $waypoints->map(fn ($waypoint) => $waypoint->place?->name ?: $waypoint->place?->public_id ?: $waypoint->place_uuid);
+    }
+}