@fleetbase/fleetops-engine 0.6.68 → 0.6.70

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

@@ -34,17 +34,20 @@ class OrderInsightsCapability extends AbstractFleetOpsAICapability
             return ['authorized' => false, 'message' => 'Current user cannot access Fleet-Ops orders.'];
         }
 
-        $prompt = $this->prompt($task);
-        $window = $this->dateWindow($prompt);
-        $amount = $this->amountThreshold($prompt);
-        $query  = $this->orderQuery(session('company'));
+        $prompt   = $this->prompt($task);
+        $window   = $this->dateWindow($prompt);
+        $amount   = $this->amountThreshold($prompt);
+        $currency = $this->currency();
+        $minor    = $amount !== null ? $this->toMinorUnits($amount, $currency) : null;
+        $query    = $this->orderQuery(session('company'));
 
         if ($window) {
             $query->whereBetween('created_at', [$window['start'], $window['end']]);
         }
 
-        if ($amount !== null) {
-            $query->whereHas('transaction', fn ($transaction) => $transaction->where('amount', '>', $amount));
+        if ($minor !== null) {
+            // Transaction amounts are stored in the currency's minor unit (e.g. cents).
+            $query->whereHas('transaction', fn ($transaction) => $transaction->where('amount', '>', $minor));
         }
 
         $total = (clone $query)->count();
@@ -59,6 +62,7 @@ class OrderInsightsCapability extends AbstractFleetOpsAICapability
                 'end'      => $window['end']->toIso8601String(),
             ] : null,
             'amount_threshold'  => $amount,
+            'amount_currency'   => $amount !== null ? $currency : null,
             'count'             => $total,
             'counts_by_status'  => (clone $query)
                 ->selectRaw('status, count(*) as aggregate')
@@ -83,6 +87,35 @@ class OrderInsightsCapability extends AbstractFleetOpsAICapability
         return null;
     }
 
+    /**
+     * Converts a major-unit amount (e.g. 500.00) to the minor units transactions are stored in,
+     * honoring the currency's ISO-4217 exponent (JPY has none, BHD has three).
+     */
+    protected function toMinorUnits(float $amount, string $currency): int
+    {
+        $exponent = 2;
+
+        try {
+            if (class_exists(\Money\Currencies\ISOCurrencies::class)) {
+                $exponent = (new \Money\Currencies\ISOCurrencies())->subunitFor(new \Money\Currency(strtoupper($currency)));
+            }
+        } catch (\Throwable) {
+            $exponent = 2;
+        }
+
+        return (int) round($amount * (10 ** $exponent));
+    }
+
+    /**
+     * @codeCoverageIgnore
+     */
+    protected function currency(): string
+    {
+        $company = function_exists('session') ? \Fleetbase\Models\Company::where('uuid', session('company'))->first(['uuid', 'currency']) : null;
+
+        return strtoupper((string) ($company?->currency ?: 'USD'));
+    }
+
     protected function dateWindow(string $prompt): ?array
     {
         return $this->relativeDateResolver()->resolveWindow($prompt);
@@ -90,7 +123,7 @@ class OrderInsightsCapability extends AbstractFleetOpsAICapability
 
     protected function orderQuery(?string $companyUuid): mixed
     {
-        return Order::where('company_uuid', $companyUuid);
+        return $this->scopeToPermission(Order::where('company_uuid', $companyUuid), 'fleet-ops list order');
     }
 
     protected function relativeDateResolver(): AiRelativeDateResolver

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

@@ -48,19 +48,69 @@ class SearchResourcesCapability extends AbstractFleetOpsAICapability
         $prompt = (string) $task->prompt;
         $terms  = $this->searchTerms($prompt);
 
-        return [
+        if (empty($terms)) {
+            return [
+                'query_terms' => [],
+                'results'     => [],
+                'message'     => 'The prompt did not reference a specific Fleet-Ops record, so no records were searched.',
+            ];
+        }
+
+        return $this->searchAll($terms);
+    }
+
+    /**
+     * Search the given resource types (all when null) for the terms. A failing search is reported
+     * without discarding the others.
+     */
+    protected function searchAll(array $terms, ?array $types = null): array
+    {
+        $results  = [];
+        $failed   = [];
+        $searches = [
+            'orders'       => fn () => $this->orders($terms),
+            'vehicles'     => fn () => $this->vehicles($terms),
+            'drivers'      => fn () => $this->drivers($terms),
+            'work_orders'  => fn () => $this->workOrders($terms),
+            'maintenances' => fn () => $this->maintenances($terms),
+            'devices'      => fn () => $this->devices($terms),
+            'sensors'      => fn () => $this->sensors($terms),
+            'telematics'   => fn () => $this->telematics($terms),
+        ];
+
+        if ($types !== null) {
+            $searches = array_intersect_key($searches, array_flip($types));
+        }
+
+        foreach ($searches as $resource => $search) {
+            try {
+                $results[$resource] = $search();
+            } catch (\Throwable $e) {
+                $failed[] = $resource;
+                $this->reportSearchFailure($resource, $e);
+            }
+        }
+
+        $payload = [
             'query_terms' => $terms,
-            'results'     => array_filter([
-                'orders'       => $this->orders($terms),
-                'vehicles'     => $this->vehicles($terms),
-                'drivers'      => $this->drivers($terms),
-                'work_orders'  => $this->workOrders($terms),
-                'maintenances' => $this->maintenances($terms),
-                'devices'      => $this->devices($terms),
-                'sensors'      => $this->sensors($terms),
-                'telematics'   => $this->telematics($terms),
-            ]),
+            'results'     => array_filter($results),
         ];
+
+        if (!empty($failed)) {
+            $payload['unavailable_search'] = $failed;
+        }
+
+        return $payload;
+    }
+
+    /**
+     * @codeCoverageIgnore
+     */
+    protected function reportSearchFailure(string $resource, \Throwable $e): void
+    {
+        if (function_exists('report')) {
+            report($e);
+        }
     }
 
     protected function matchesPrompt(string $prompt): bool
@@ -76,7 +126,7 @@ class SearchResourcesCapability extends AbstractFleetOpsAICapability
 
         return $this->orderSearchQuery()
             ->where(function ($query) use ($terms) {
-                $this->whereLikeAny($query, ['public_id', 'internal_id', 'uuid', 'status', 'type'], $terms);
+                $this->whereLikeAny($query, ['public_id', 'internal_id'], $terms);
                 $query->orWhereHas('trackingNumber', fn ($tracking) => $this->whereLikeAny($tracking, ['tracking_number', 'barcode'], $terms));
             })
             ->limit(5)
@@ -127,7 +177,7 @@ class SearchResourcesCapability extends AbstractFleetOpsAICapability
 
         return $this->driverSearchQuery()
             ->where(function ($query) use ($terms) {
-                $this->whereLikeAny($query, ['public_id', 'uuid', 'drivers_license_number', 'status'], $terms);
+                $this->whereLikeAny($query, ['public_id', 'internal_id', 'drivers_license_number'], $terms);
                 $query->orWhereHas('user', fn ($user) => $this->whereLikeAny($user, ['name', 'email', 'phone'], $terms));
             })
             ->limit(5)
@@ -146,27 +196,27 @@ class SearchResourcesCapability extends AbstractFleetOpsAICapability
 
     protected function workOrders(array $terms): array
     {
-        return $this->generic(WorkOrder::class, 'fleet-ops see work-order', ['public_id', 'uuid', 'code', 'subject', 'status', 'priority'], 'console.fleet-ops.maintenance.work-orders.index.details', $terms);
+        return $this->generic(WorkOrder::class, 'fleet-ops see work-order', ['public_id', 'code', 'subject'], 'console.fleet-ops.maintenance.work-orders.index.details', $terms);
     }
 
     protected function maintenances(array $terms): array
     {
-        return $this->generic(Maintenance::class, 'fleet-ops see maintenance', ['public_id', 'uuid', 'status', 'type', 'summary', 'notes'], 'console.fleet-ops.maintenance.maintenances.index.details', $terms);
+        return $this->generic(Maintenance::class, 'fleet-ops see maintenance', ['public_id', 'summary', 'notes'], 'console.fleet-ops.maintenance.maintenances.index.details', $terms);
     }
 
     protected function devices(array $terms): array
     {
-        return $this->generic(Device::class, 'fleet-ops see device', ['public_id', 'uuid', 'name', 'device_id', 'imei', 'serial_number', 'status'], 'console.fleet-ops.connectivity.devices.index.details', $terms);
+        return $this->generic(Device::class, 'fleet-ops see device', ['public_id', 'name', 'device_id', 'imei', 'serial_number'], 'console.fleet-ops.connectivity.devices.index.details', $terms);
     }
 
     protected function sensors(array $terms): array
     {
-        return $this->generic(Sensor::class, 'fleet-ops see sensor', ['public_id', 'uuid', 'name', 'internal_id', 'serial_number', 'imei', 'type', 'sensor_type', 'status'], 'console.fleet-ops.connectivity.sensors.index.details', $terms);
+        return $this->generic(Sensor::class, 'fleet-ops see sensor', ['public_id', 'name', 'internal_id', 'serial_number', 'imei'], 'console.fleet-ops.connectivity.sensors.index.details', $terms);
     }
 
     protected function telematics(array $terms): array
     {
-        return $this->generic(Telematic::class, 'fleet-ops see telematic', ['public_id', 'uuid', 'name', 'provider', 'status'], 'console.fleet-ops.connectivity.telematics.details', $terms);
+        return $this->generic(Telematic::class, 'fleet-ops see telematic', ['public_id', 'name'], 'console.fleet-ops.connectivity.telematics.details', $terms);
     }
 
     protected function generic(string $modelClass, string $permission, array $columns, string $route, array $terms): array
@@ -193,23 +243,35 @@ class SearchResourcesCapability extends AbstractFleetOpsAICapability
 
     protected function orderSearchQuery()
     {
-        return Order::with(['transaction', 'trackingNumber'])
-            ->where('company_uuid', session('company'));
+        return $this->scopeToPermission(
+            Order::with(['transaction', 'trackingNumber'])->where('company_uuid', session('company')),
+            'fleet-ops list order'
+        );
     }
 
     protected function vehicleSearchQuery()
     {
-        return Vehicle::where('company_uuid', session('company'));
+        return $this->scopeToPermission(Vehicle::where('company_uuid', session('company')), 'fleet-ops list vehicle');
     }
 
     protected function driverSearchQuery()
     {
-        return Driver::with('user')
-            ->where('company_uuid', session('company'));
+        return $this->scopeToPermission(Driver::with('user')->where('company_uuid', session('company')), 'fleet-ops list driver');
     }
 
     protected function genericSearchQuery(string $modelClass)
     {
-        return $modelClass::where('company_uuid', session('company'));
+        $permission = match ($modelClass) {
+            WorkOrder::class   => 'fleet-ops list work-order',
+            Maintenance::class => 'fleet-ops list maintenance',
+            Device::class      => 'fleet-ops list device',
+            Sensor::class      => 'fleet-ops list sensor',
+            Telematic::class   => 'fleet-ops list telematic',
+            default            => null,
+        };
+
+        $query = $modelClass::where('company_uuid', session('company'));
+
+        return $permission ? $this->scopeToPermission($query, $permission) : $query;
     }
 }

package/server/src/Support/Ai/FleetOpsAiConsoleCommands.php

@@ -0,0 +1,122 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai;
+
+/**
+ * Fleet-Ops pages and dialogs Fleetbase AI may offer to open. Definitions are plain arrays so Fleet-Ops
+ * does not depend on the AI extension's classes; nothing runs until the user confirms it in the console.
+ */
+class FleetOpsAiConsoleCommands
+{
+    public const ENGINE = '@fleetbase/fleetops-engine';
+
+    protected const DOCS = 'https://fleetbase.io/docs/fleet-ops';
+
+    public static function all(): array
+    {
+        return array_merge(static::resources(), static::settings());
+    }
+
+    /**
+     * Open, create, import, and view commands for Fleet-Ops records.
+     */
+    public static function resources(): array
+    {
+        $resources = [
+            // key => [singular, plural, list route, new route, detail route, permission resource, actions service, supports import, docs path, keywords]
+            'orders'       => ['order', 'Orders', 'operations.orders.index', 'operations.orders.index.new', 'operations.orders.index.details', 'order', 'order-actions', 'importOrders', 'operations/orders', ['dispatch', 'delivery', 'shipment', 'job']],
+            'drivers'      => ['driver', 'Drivers', 'management.drivers.index', 'management.drivers.index.new', 'management.drivers.index.details', 'driver', 'driver-actions', 'import', 'resources/drivers', ['courier', 'navigator']],
+            'vehicles'     => ['vehicle', 'Vehicles', 'management.vehicles.index', 'management.vehicles.index.new', 'management.vehicles.index.details', 'vehicle', 'vehicle-actions', 'import', 'resources/vehicles', ['truck', 'van', 'car', 'fleet']],
+            'contacts'     => ['contact', 'Contacts', 'management.contacts.index', 'management.contacts.index.new', 'management.contacts.index.details', 'contact', 'contact-actions', 'import', 'resources/contacts', ['person']],
+            'customers'    => ['customer', 'Customers', 'management.contacts.customers', 'management.contacts.customers.new', 'management.contacts.customers.details', 'contact', 'customer-actions', 'import', 'resources/contacts', ['client', 'contacts']],
+            'places'       => ['place', 'Places', 'management.places.index', 'management.places.index.new', 'management.places.index.details', 'place', 'place-actions', 'import', 'resources/places', ['address', 'location', 'depot', 'warehouse']],
+            'fleets'       => ['fleet', 'Fleets', 'management.fleets.index', 'management.fleets.index.new', 'management.fleets.index.details', 'fleet', 'fleet-actions', null, 'resources/fleets', ['team']],
+            'issues'       => ['issue', 'Issues', 'management.issues.index', 'management.issues.index.new', 'management.issues.index.details', 'issue', 'issue-actions', null, 'resources/issues', ['problem', 'incident']],
+            'work_orders'  => ['work order', 'Work Orders', 'maintenance.work-orders.index', 'maintenance.work-orders.index.new', 'maintenance.work-orders.index.details', 'work-order', 'work-order-actions', null, 'maintenance/work-orders', ['maintenance', 'repair']],
+            'maintenances' => ['maintenance', 'Maintenances', 'maintenance.maintenances.index', 'maintenance.maintenances.index.new', 'maintenance.maintenances.index.details', 'maintenance', 'maintenance-actions', null, 'maintenance', ['service', 'repair']],
+        ];
+
+        $commands = [];
+
+        foreach ($resources as $key => [$singular, $plural, $listRoute, $newRoute, $detailRoute, $permission, $service, $import, $docs, $keywords]) {
+            $base = [
+                'breadcrumb' => "Fleet-Ops › {$plural}",
+                'keywords'   => array_merge(['fleet-ops', $singular], $keywords),
+                'docs_url'   => static::DOCS . "/{$docs}",
+                'module'     => 'fleet-ops',
+            ];
+
+            $commands[] = $base + [
+                'id'          => "fleet-ops.{$key}.open",
+                'label'       => "Open {$plural}",
+                'description' => "Go to the Fleet-Ops {$plural} list.",
+                'steps'       => [['type' => 'navigate', 'route' => "console.fleet-ops.{$listRoute}"]],
+                'permissions' => ["fleet-ops list {$permission}"],
+            ];
+
+            $commands[] = $base + [
+                'id'          => "fleet-ops.{$key}.create",
+                'label'       => "Create {$singular}",
+                'description' => "Open the new {$singular} form in Fleet-Ops.",
+                'steps'       => [['type' => 'navigate', 'route' => "console.fleet-ops.{$newRoute}"]],
+                'permissions' => ["fleet-ops create {$permission}"],
+                'keywords'    => array_merge($base['keywords'], ['new', 'add', 'create']),
+            ];
+
+            $commands[] = $base + [
+                'id'          => "fleet-ops.{$key}.view",
+                'label'       => "Open {$singular}",
+                'description' => "Open a specific {$singular} by its public id.",
+                'steps'       => [['type' => 'navigate', 'route' => "console.fleet-ops.{$detailRoute}", 'models' => ['public_id']]],
+                'permissions' => ["fleet-ops see {$permission}"],
+                'params'      => ['public_id' => ['type' => 'string', 'description' => "The {$singular} public id."]],
+            ];
+
+            if ($import) {
+                $commands[] = $base + [
+                    'id'          => "fleet-ops.{$key}.import",
+                    'label'       => "Import {$plural}",
+                    'description' => "Go to {$plural} in Fleet-Ops and open the spreadsheet import, including the template download.",
+                    'steps'       => [
+                        ['type' => 'navigate', 'route' => "console.fleet-ops.{$listRoute}"],
+                        ['type' => 'service', 'engine' => static::ENGINE, 'service' => $service, 'method' => $import],
+                    ],
+                    'permissions' => ["fleet-ops import {$permission}"],
+                    'keywords'    => array_merge($base['keywords'], ['import', 'spreadsheet', 'csv', 'excel', 'xlsx', 'template', 'bulk', 'upload']),
+                ];
+            }
+        }
+
+        return $commands;
+    }
+
+    public static function settings(): array
+    {
+        $settings = [
+            'map'           => ['Map', 'map-settings', ['map', 'provider', 'google maps', 'leaflet', 'openstreetmap', 'tiles', 'view maps']],
+            'navigator-app' => ['Navigator App', 'navigator-settings', ['navigator', 'driver app', 'mobile app', 'onboard']],
+            'routing'       => ['Routing', 'routing-settings', ['routing', 'route', 'optimization', 'osrm', 'distance']],
+            'notifications' => ['Notifications', 'notification-settings', ['notification', 'alert', 'email', 'sms']],
+            'custom-fields' => ['Custom Fields', 'custom-field', ['custom field', 'field', 'attribute']],
+            'scheduling'    => ['Scheduling', null, ['schedule', 'shift', 'calendar']],
+        ];
+
+        $commands = [];
+
+        foreach ($settings as $route => [$label, $permission, $keywords]) {
+            $commands[] = [
+                'id'          => 'fleet-ops.settings.' . str_replace('-', '_', $route) . '.open',
+                'label'       => "Open {$label} settings",
+                'breadcrumb'  => "Fleet-Ops › Settings › {$label}",
+                'description' => "Go to the Fleet-Ops {$label} settings.",
+                'steps'       => [['type' => 'navigate', 'route' => "console.fleet-ops.settings.{$route}"]],
+                'permissions' => $permission ? ["fleet-ops view {$permission}"] : [],
+                'keywords'    => array_merge(['fleet-ops', 'settings', 'configure'], $keywords),
+                'docs_url'    => static::DOCS . "/settings/{$route}",
+                'module'      => 'fleet-ops',
+            ];
+        }
+
+        return $commands;
+    }
+}

package/server/src/Support/Ai/Tools/CreateOrderTool.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Tools;
+
+use Fleetbase\Ai\Contracts\AIToolCapabilityInterface;
+use Fleetbase\Ai\Models\AiTask;
+use Fleetbase\Ai\Support\AiToolContext;
+use Fleetbase\FleetOps\Support\Ai\Capabilities\CreateOrderPreviewCapability;
+
+/**
+ * Lets the model prepare a Fleet-Ops order draft from structured fields. The draft is shown to the user
+ * as a preview card; the order is only created when the user applies it.
+ */
+class CreateOrderTool extends CreateOrderPreviewCapability implements AIToolCapabilityInterface
+{
+    public function toolName(): string
+    {
+        return 'propose_create_order';
+    }
+
+    public function toolDescription(): string
+    {
+        return 'Prepare a Fleet-Ops order draft for the user to review. Call once per order (several calls prepare several drafts). '
+            . 'Each draft appears as a card the user must confirm; the order is NOT created by this tool. '
+            . 'Pass addresses or saved place names exactly as the user gave them. Use ISO 8601 for scheduled_at, resolved with the temporal context. '
+            . 'Only fill fields the user provided or explicitly asked you to make up (for example test data). After calling, tell the user to review the draft card; never claim the order exists.';
+    }
+
+    public function toolParameters(): array
+    {
+        return [
+            'type'       => 'object',
+            'properties' => [
+                'pickup'       => ['type' => 'string', 'description' => 'Pickup address or saved place name.'],
+                'dropoff'      => ['type' => 'string', 'description' => 'Dropoff address or saved place name.'],
+                'scheduled_at' => ['type' => 'string', 'description' => 'Optional ISO 8601 date and time.'],
+                'driver'       => ['type' => 'string', 'description' => 'Optional driver name or public id.'],
+                'vehicle'      => ['type' => 'string', 'description' => 'Optional vehicle name, plate, or public id.'],
+                'order_config' => ['type' => 'string', 'description' => 'Optional order configuration key, e.g. transport.'],
+                'notes'        => ['type' => 'string', 'description' => 'Optional notes for the order.'],
+                'dispatch'     => ['type' => 'boolean', 'description' => 'Dispatch immediately. Only true when the user asked for it.'],
+            ],
+            'required'             => ['pickup', 'dropoff'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function availableFor(AiToolContext $context): bool
+    {
+        return $context->audience->canAll($this->permissions());
+    }
+
+    public function invoke(AiTask $task, array $arguments, AiToolContext $context): array
+    {
+        $draft = array_filter([
+            'payload' => array_filter([
+                'pickup_query'  => $this->argument($arguments, 'pickup'),
+                'dropoff_query' => $this->argument($arguments, 'dropoff'),
+            ]),
+            'scheduled_at'  => $this->argument($arguments, 'scheduled_at'),
+            'driver_query'  => $this->argument($arguments, 'driver'),
+            'vehicle_query' => $this->argument($arguments, 'vehicle'),
+            'type'          => $this->argument($arguments, 'order_config'),
+            'notes'         => $this->argument($arguments, 'notes'),
+            'dispatched'    => (bool) ($arguments['dispatch'] ?? false),
+        ], fn ($value) => $value !== null && $value !== []);
+
+        $preview = $context->addActionPreview($this, $this->preview($task, ['source' => 'tool', 'draft' => $draft]));
+
+        return [
+            'preview_id'     => $preview['preview_id'],
+            'ready'          => $preview['ready'] ?? false,
+            'missing_fields' => $preview['missing_fields'] ?? [],
+            'fields'         => $preview['fields'] ?? [],
+            'status'         => 'draft_shown_to_user',
+            'message'        => 'A draft order card is shown to the user. The order does not exist until the user reviews the card and clicks ' . ($preview['apply_label'] ?? 'Create order') . '.',
+        ];
+    }
+
+    protected function argument(array $arguments, string $key): ?string
+    {
+        $value = trim((string) ($arguments[$key] ?? ''));
+
+        return $value === '' ? null : $value;
+    }
+}

package/server/src/Support/Ai/Tools/ImportOrdersTool.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Tools;
+
+use Fleetbase\Ai\Contracts\AIToolCapabilityInterface;
+use Fleetbase\Ai\Models\AiTask;
+use Fleetbase\Ai\Support\AiToolContext;
+use Fleetbase\FleetOps\Support\Ai\Capabilities\ImportOrdersPreviewCapability;
+
+/**
+ * Explains what a Fleet-Ops order import needs. Fleetbase AI cannot process an uploaded spreadsheet,
+ * so this only reports the accepted formats and required columns for the user to act on themselves.
+ */
+class ImportOrdersTool extends ImportOrdersPreviewCapability implements AIToolCapabilityInterface
+{
+    public function toolName(): string
+    {
+        return 'fleetops_import_requirements';
+    }
+
+    public function toolDescription(): string
+    {
+        return 'Report what a Fleet-Ops order or resource import needs: accepted file formats and the columns a spreadsheet must contain. '
+            . 'Use it when the user asks about importing or bulk uploading orders, vehicles, or drivers from a spreadsheet. '
+            . 'This does NOT import anything and cannot read an uploaded file; never tell the user rows were imported.';
+    }
+
+    public function toolParameters(): array
+    {
+        return [
+            'type'                 => 'object',
+            'properties'           => new \stdClass(),
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function availableFor(AiToolContext $context): bool
+    {
+        return $context->audience->canAll($this->permissions());
+    }
+
+    public function invoke(AiTask $task, array $arguments, AiToolContext $context): array
+    {
+        $requirements = $this->resolve($task);
+
+        return [
+            'accepted_sources' => $requirements['accepted_sources'] ?? [],
+            'minimum_columns'  => $requirements['minimum_columns'] ?? [],
+            'can_import_here'  => false,
+            'message'          => $requirements['message'] ?? 'Fleetbase AI cannot process uploaded spreadsheets.',
+        ];
+    }
+}

package/server/src/Support/Ai/Tools/OptimizeOrderRouteTool.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Ai\Tools;
+
+use Fleetbase\Ai\Contracts\AIToolCapabilityInterface;
+use Fleetbase\Ai\Models\AiTask;
+use Fleetbase\Ai\Support\AiToolContext;
+use Fleetbase\FleetOps\Support\Ai\Capabilities\OptimizeOrderRouteCapability;
+
+/**
+ * Lets the model propose a resequenced waypoint order for a Fleet-Ops order. The proposal is shown as
+ * a preview card; the route is only changed when the user applies it.
+ */
+class OptimizeOrderRouteTool extends OptimizeOrderRouteCapability implements AIToolCapabilityInterface
+{
+    public function toolName(): string
+    {
+        return 'propose_optimize_order_route';
+    }
+
+    public function toolDescription(): string
+    {
+        return 'Prepare an optimized waypoint sequence for one Fleet-Ops order, for the user to review. '
+            . 'Use it when the user asks to optimize, reorder, or resequence the stops on an order. '
+            . 'Each proposal appears as a card the user must confirm; the route is NOT changed by this tool. '
+            . 'After calling, tell the user to review the card; never claim the route was changed.';
+    }
+
+    public function toolParameters(): array
+    {
+        return [
+            'type'       => 'object',
+            'properties' => [
+                'order' => ['type' => 'string', 'description' => 'The order public id, internal id, or UUID, exactly as the user gave it.'],
+            ],
+            'required'             => ['order'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function availableFor(AiToolContext $context): bool
+    {
+        return $context->audience->canAll($this->permissions());
+    }
+
+    public function invoke(AiTask $task, array $arguments, AiToolContext $context): array
+    {
+        $order = trim((string) ($arguments['order'] ?? ''));
+
+        if ($order === '') {
+            return ['error' => 'invalid_arguments', 'message' => 'An order id is required to optimize a route.'];
+        }
+
+        // The capability resolves the order from the prompt text, so hand it a copy carrying just the
+        // identifier the model supplied. The copy is never saved.
+        $probe         = clone $task;
+        $probe->prompt = $order;
+
+        $preview = $context->addActionPreview($this, $this->preview($probe));
+
+        return [
+            'preview_id'     => $preview['preview_id'],
+            'ready'          => $preview['ready'] ?? false,
+            'missing_fields' => $preview['missing_fields'] ?? [],
+            'fields'         => $preview['fields'] ?? [],
+            'status'         => 'proposal_shown_to_user',
+            'message'        => $preview['message'] ?? 'A route proposal card is shown to the user.',
+        ];
+    }
+}