Vibedebug Bundle Laravel Package

Getting Started

Still a Symfony bundle, not a Laravel package. 0.3.0 doesn't change that: it depends on symfony/framework-bundle, the DI container, and symfony/ai. No extra.laravel.providers, no package discovery, no facade. Two realistic paths for a Laravel developer:

1. You run a Symfony service (or sidecar) in a polyglot stack and want AI-assisted debugging there — 0.3.0 makes this noticeably more useful, because a generic agent (not just the bundle's own exception subscriber) can now query the profiler.
2. You treat it as a reference implementation and port the pattern to Laravel (Telescope + report() + laravel/ai/Prism + Ignition, or laravel/mcp for the tool-exposure half).

What 0.3.0 actually adds: two AI tools — vibedebug_profiler_summary (compact profile + list of available collectors) and vibedebug_profiler_export_collectors (dump selected collectors' data) — addressed by a profiler token. They're consumable by internal agents (symfony/ai-agent) or external agents over MCP / Symfony AI Mate. This is a shift in shape: v0.2.x was "exception happens → ask a model → get a suggestion." v0.3.0 is "an agent can pull profiler context on demand and drive its own investigation loop." That's the part worth caring about.

Minimal steps (Symfony side):

composer require milton/vibedebug-bundle symfony/ai
# 1. Register the bundle class in config/bundles.php (class name is in the README)
# 2. Create config/packages/<alias>.yaml — config keys live in
#    src/DependencyInjection/*Extension.php, which remains the fastest source of truth
# 3. Provide AI platform credentials in .env (OpenAI/Anthropic/Ollama bridge)
# 4. For the new tools: ensure the profiler is enabled in dev, then either
#    wire the tools into symfony/ai-agent, or expose them over MCP and point
#    your agent at that server.

Where to look first, in this order:

• README quickstart (bundle class, config alias, command name).
• DependencyInjection/<Name>Extension.php — config tree, defaults, and which tool/service definitions get registered. Confirm whether the profiler tools are on by default or opt-in; the notes don't say.
• src/ tool classes behind vibedebug_profiler_* — the actual input schema (token, collector names, limits) and output shape. This is your contract.
• EventSubscriber/ and Command/ — the older capture-and-explain path, still the more mature code.
• composer.json — symfony/ai version range and platform bridges, plus any new symfony/ai-agent/MCP requirement.

First use case: hit a deliberately broken route in dev, grab the profiler token out of the web debug toolbar (or var/cache/dev/profiler), then call vibedebug_profiler_summary through your agent and ask it to export the Doctrine/request/log collectors and explain the failure. Immediately repeat with a request carrying a password or API key in the body and an auth header — the export tool is now a direct read path to exactly that data. If the redaction story isn't clear, stop there.

Still pre-1.0: a double-digit star count, essentially zero dependents, and a short release history (0.2.3 → 0.3.0). Pin an exact version and read the source before trusting it.

Implementation Patterns

Pattern 1 — Agent-driven profiler triage (new in 0.3.0, and the best use of it). The intended loop is: a failure occurs → you (or CI, or an on-call bot) have a profiler token → agent calls vibedebug_profiler_summary to see which collectors have signal → agent calls vibedebug_profiler_export_collectors with only those → model reasons over the export. The two-tool split matters: it keeps the payload small and lets the agent decide what's relevant rather than dumping everything. Encode that discipline in your agent's system prompt — "summary first, export at most N collectors, never export request/dump without redaction."

Pattern 2 — Dev-only, exception-driven capture (the pre-0.3.0 path). Exception → collect context (trace, request, recent logs, container params) → send to a model with a fixed prompt → write suggestion to a log or profiler panel → human applies the patch. Never auto-apply generated diffs, and never enable in prod: it costs money per error and ships stack traces to a third party.

Pattern 3 — Sidecar for a Laravel app. Put the Symfony implementation behind an internal HTTP endpoint and have Laravel's App\Exceptions\Handler::report() POST a sanitized payload (message, class, trace, route, app version, trace ID). With 0.3.0 you can go further and have the sidecar expose its MCP server internally, so a Laravel-side agent can fetch Symfony profiler context for cross-service debugging. Keep credentials and the MCP endpoint on the internal network only.

Pattern 4 — Port the concept to Laravel (usually still the better call). The mapping now has an MCP column:

// Illustrative Laravel port — not the bundle's API
public function report(Throwable $e): void
{
    parent::report($e);

    if (! app()->isLocal() || $e instanceof ValidationException) {
        return;
    }

    DebugAiJob::dispatch([
        'class'   => $e::class,
        'message' => $e->getMessage(),
        'trace'   => collect($e->getTrace())->take(15)->all(),
        'route'   => request()->route()?->getName(),
        'input'   => request()->except(['password', 'token', 'authorization']),
        'user_id' => auth()->id(),
    ])->onQueue('debug');
}

Pattern 5 — Queue, cache, and fingerprint. Non-negotiables once wired up:

• Dispatch the AI call to a queue. A synchronous model round-trip inside report() turns a 500 into a 30-second 500.
• Key responses by an exception fingerprint (class + normalized message + top frame). Identical errors hit the cache, not the model. In a busy app that's $5/month vs $500/month.
• For the profiler tools, cache by (token, collector set) — agents will happily re-request the same export in a loop.

Pattern 6 — Human-in-the-loop audit trail. Land output in a debug_ai_suggestions table with exception_hash, model, prompt, response, accepted_at. Gives you an audit trail, lets you measure hit rate, and means you can delete rows when someone inevitably pastes a secret into a trace or a profiler export.

Gotchas and Tips

Framework coupling (unchanged). No package discovery, no facade. Don't shoehorn it into Laravel's container — the service tags and event-dispatcher wiring won't resolve. Run it in Symfony.

The new tools are a read API over your dev data. vibedebug_profiler_export_collectors will happily return whatever a collector captured — Doctrine query bindings, request headers, session payloads, dump() output, env values. That's the whole point, and it's also the risk. Before exposing the MCP server beyond localhost: restrict collector names per-environment in config, hard-cap response size, and treat the profiler token as a bearer credential (it is one). Test with a secret-laden request, don't assume.

Profiler token lifecycle. Tokens are per-request and live on disk under var/cache/dev/profiler (and are garbage-collected). Implications: an agent loop needs a fresh token per run, tokens expire mid-investigation on long sessions, and tokens are sequential-ish/guessable enough that you should never expose the profiler or MCP endpoint on a public interface. If the token isn't found, profiler_summary will fail in a way that looks like a tool bug rather than a stale token — check the file exists before blaming the agent.

symfony/ai and the agent/MCP layer are the risk surface. Now two young dependencies determine config shape and behavior: the platform bridge (OpenAI vs Anthropic vs Ollama) and the agent transport (internal symfony/ai-agent vs MCP / AI Mate). Pin all of them. When config doesn't match the README, the DI extension is authoritative.

Tool schemas are the contract — and they can move under you. 0.3.0's release notes show no breaking changes, but tool names, argument names (collector selection, token param), and output envelope are brand-new surface in a pre-1.0 package. Snapshot a real request/response pair into a test fixture so a renamed argument fails loudly in CI rather than as a vague "the agent got confused."

Secret leakage remains the headline gotcha. Stack traces and collector exports carry connection strings, query bindings, env values, auth headers. Before anything leaves the process: redact known key patterns, cap payload size hard (e.g. 32KB), strip $_ENV, prefer a local Ollama model if data can't cross a network boundary. For the MCP path, remember the agent decides what to export — your guardrails have to live in the tool/server, not in a polite prompt.

Debugging the debugger. If nothing fires:

• Confirm environment gating — most bundles like this default to dev only, and the profiler tools are meaningless without the profiler enabled.
• bin/console debug:event-dispatcher to verify the subscriber is registered.
• bin/console debug:container <service> to confirm the tool services exist and what was injected.
• If the tools don't appear in your agent, list the MCP server's advertised tools first — a tool that isn't listed is a DI/config problem, not a model problem.
• Log the raw prompt, the raw tool arguments, and the raw response at debug level. "It gave a bad answer" is usually "the prompt was missing the trace" or "the agent exported the wrong collector."

Extension points. The DI extension's config tree plus dispatched events are where you customize. If the bundle dispatches an event before the model/tool call, listen there and redact. If it doesn't, decorate the client or tool service — cleaner than patching vendor code.

Bus factor. Tiny star count and no dependents means: no Stack Overflow answers, no blog posts, no guarantee 0.4.0 won't rename a tool or move a config key. If you build on it, fork it or path-repository it, and write a smoke test that asserts both the capture path and the profiler-tool round trip work, so an upstream change fails in CI instead of silently in production.

Version discipline. 0.3.0 lands on top of at least 0.2.3, so this is an actively-moving pre-1.0 package — treat upgrades as code review, not composer update. Before any bump, diff the source (not the changelog, which may be thin) and specifically diff the tool input/output schemas, since that's what your agent prompts depend on.