Laravel Loop Filament Laravel Package

Getting Started

Prerequisites — check these before writing any code. This is a bridge package: it is only worth installing if you already run Filament for back-office tooling and laravel-loop is already a working part of that app. Verify both:

composer show filament/filament kirschbaum-development/laravel-loop
php artisan about   # confirms panels + providers are booting
grep -n "FILAMENT\|LOOP" .env

If Loop is headless in your app (queued jobs, API calls only, no human who needs to trigger or inspect a run), stop here — the package has no surface to add.

Install with an explicit constraint. Because this is 0.1.x with no BC promise, do not rely on composer require picking a version for you. Note the Filament major first: the 0.1.5 release is a Filament v4 compatibility patch, so the mapping is effectively Filament 3 → 0.1.4, Filament 4 → 0.1.5+. Read the composer.json in PR #9 to confirm whether the constraint was widened (^3.0|^4.0) or narrowed to ^4.0 — that one detail decides whether 0.1.5 is a safe patch for a v3 app or a forced co-upgrade.

composer require "kirschbaum-development/laravel-loop-filament:~0.1.5" -W
composer why-not filament/filament "4.*"   # on a v3 app: does it even resolve?

Register the plugin on the panel you actually want it on. Open app/Providers/Filament/AdminPanelProvider.php and add it inside panel():

->plugin(\Kirschbaum\LoopFilament\LoopFilamentPlugin::make())

(Confirm the exact namespace/class from src/ or the README — the plugin class and its fluent config methods are the real API here; the release notes don't document them.)

Publish what ships. Look for a service provider in src/ and its publishes() calls; typically:

php artisan vendor:publish --provider="Kirschbaum\LoopFilament\LoopFilamentServiceProvider"
php artisan filament:assets
php artisan optimize:clear

Where to look first, in order: the plugin class (what's configurable — navigation group, label, icon, authorization callbacks), the src/Resources directory (which Loop models are exposed and how they map to Eloquent), then the config file you just published.

First use case — the end-to-end smoke test. Register on a staging panel, log in as an admin, find the Loop navigation group, trigger a trivial agent that has no side-effecting tools, then open the run/conversation history page and confirm the record exists. That single pass proves the whole wire: Loop config, queue driver, DB tables, panel registration, and authorization. Do it before you customize anything.

Implementation Patterns

Scope the plugin to one panel. Register it only on the internal/admin panel provider — never on a customer-facing one. Agents can invoke tools with real side effects, so panel visibility is your security boundary. If you have multiple panels, keep a dedicated OpsPanelProvider.

Front authorization with gates. Filament policies are the natural control, but if the package's resources ship without policies, close the gap yourself:

LoopFilamentPlugin::make()
    ->authorize(fn () => auth()->user()?->hasRole('ops'));

Also confirm the run-triggering actions are gated — browsing history is low-risk, invoking an agent is not. Audit both.

Treat the history pages as your primary debugging tool. The highest-value day-to-day use isn't the create form; it's opening a failed run, reading the prompt and tool-call sequence, and comparing against the payload a user reported. Reach for this before adding Log::info inside an agent. Build the habit of linking an agent run ID into your error tracker so support can jump straight to the panel.

Extend by subclassing, not forking. When you need an extra column, filter, or custom action, subclass the shipped Resource (or register your own Resource against the same Loop model) rather than editing vendor code. Check first whether the package's resources are final — if they are, your extension point is a separate resource, and you should plan for it.

Reproduce bugs locally against a seeded agent. Keep a deterministic test agent with fake/fixture tools in your seeders so the panel always has something runnable on a fresh migrate:fresh --seed. That turns "operator reports weird run" into a one-minute local reproduction.

Don't lean on the panel in tests. Test agents directly (unit/feature tests against Loop), and keep the Filament surface as manual QA. Writing panel tests against a 0.x dependency couples your suite to an unstable API.

Write the version mapping down in-repo. A line in composer.json comments or a docs/dependencies.md: Filament 3 → loop-filament 0.1.4; Filament 4 → loop-filament 0.1.5+. Without it, the coupling becomes incident-time archaeology.

Gotchas and Tips

Pin it, don't caret it. At 0.1.x a patch release may legitimately change a hard constraint. Use ~0.1.5 or an exact pin in production manifests, commit the lock file, and eyeball composer.json in each tag's diff before bumping. There is no LTS and no compatibility promise.

Filament cannot install two majors at once. This package silently makes the Filament major a whole-app decision. Your v4 upgrade date is set by the slowest Filament plugin in your tree — this one is necessary but not sufficient. Inventory every Filament-dependent package before scheduling the bump.

The 0.1.5 patch may be constraint-only and untested against v4. "Updates Filament dependencies for v4 compatibility" is ambiguous. Read the actual PR #9 diff: if no registration/API code changed, treat v4 support as claimed, not proven, and smoke-test the full surface yourself — listing, run pages, actions, history views, asset publishing, and authorization.

Long-running agent runs will hang the request. If a Filament action triggers a synchronous agent call, you'll hit max_execution_time and leave the operator staring at a spinner. Ensure Loop dispatches to a queue and the page reflects status (look for ->poll() on the resource table/action). If the package doesn't poll, that's your first customization.

Tenancy is the sharp edge. On a tenanted Filament panel, verify the Loop resources actually respect Filament's tenant scoping. If Loop records aren't tenant-scoped, you have cross-tenant data exposure in the admin panel — check getEloquentQuery() on the shipped resources before enabling on anything multi-tenant.

Navigation not appearing? Work the list in order: plugin registered on that panel → canAccess()/authorization callback returning true for your user → php artisan optimize:clear (Filament caches component and resource discovery in production) → php artisan route:list | grep filament to confirm the routes exist.

Asset staleness after upgrade. Run php artisan filament:assets and clear caches whenever you bump either Filament or this package; v4 changed asset handling, and stale manifests produce silently broken UI rather than errors.

Keep a fork plan. 31 stars, zero dependents, single maintainer, pre-1.0 — acceptable for internal operator tooling with a named owner, disqualifying for anything SLA- or compliance-bearing. The adapter is small enough to vendor or fork; decide the trigger for doing so now (e.g. "no release for 6 months" or "blocks our Filament upgrade") rather than during an incident.