Roadmap: Agent-Native Debugging¶

Django Orbit should evolve from a Django debugging dashboard into an agent-native observability layer: a local, privacy-conscious system that gives humans and AI agents enough structured context to move from ticket or error to root-cause hypothesis and proposed fix.

Direction¶

The future debugging workflow is likely to be hybrid:

• humans use the dashboard for inspection, trust-building and quick triage;
• agents use MCP tools, incident bundles and structured traces for investigation;
• coding agents consume the same context to propose patches, tests and pull requests;
• OpenTelemetry compatibility keeps Orbit interoperable with the wider observability ecosystem.

Orbit's differentiator should be Django-native context: request lifecycle, ORM behavior, middleware, templates, cache, storage, mail, auth/gates, jobs, signals and settings-aware safety boundaries.

Track A: High-Level MCP Tools¶

Current MCP tools expose useful raw slices. The next generation should expose investigation primitives that answer developer and agent questions directly.

Request and Endpoint Investigation¶

Exception and Error Intelligence¶

Database and ORM Analysis¶

Logs, Cache, Storage, Mail and Jobs¶

Security and Privacy-Aware Debugging¶

Ticket-to-Diagnosis Tools¶

Daily Developer Workflows¶

Track B: Incident Bundles¶

Incident Bundles are portable evidence packages generated from a request, exception group, endpoint, ticket text or natural-language query. They should be small enough for agents, structured enough for automation and readable enough for humans.

Bundle Sources¶

• family_hash for a single request lifecycle;
• exception fingerprint for grouped errors;
• endpoint path/method for route-level behavior;
• raw ticket text or pasted traceback;
• tag, query or time window.

Bundle Contents¶

Each bundle should include:

• metadata: bundle id, generated at, Orbit version, time window, source type;
• primary evidence: request summary, exception summary, endpoint stats or matched ticket terms;
• timeline: ordered events with relative offsets;
• query analysis: slow queries, duplicate signatures, callsites and EXPLAIN summaries when available;
• logs: warning/error logs near the event, grouped by logger/message shape;
• related systems: cache, jobs, mail, storage, Redis, HTTP client, gates;
• safety report: masking status, omitted fields, payload truncation and MCP exposure policy;
• hypotheses: ranked causes with supporting evidence and confidence;
• suggested next actions: reproduce, inspect file/surface, add test, check config, add index, etc.;
• agent handoff: compact JSON plus Markdown brief.

Bundle Formats¶

• incident_bundle.json for agents and automation;
• incident_bundle.md for tickets, PRs and humans;
• optional zipped export for sharing with maintainers;
• future: OTLP trace export for OpenTelemetry-compatible backends.

MCP Tools for Bundles¶

• create_incident_bundle(source_type, source_id_or_text, hours=72)
• get_incident_bundle(bundle_id)
• list_recent_incident_bundles(limit=20)
• export_incident_bundle(bundle_id, format="json|markdown")
• redact_incident_bundle(bundle_id, policy="agent_safe")

Storage Model¶

Start without a new table: generate bundles on demand from OrbitEntry and return them directly. Add persisted bundles later only if users need sharing, comments or issue tracking.

Track C: OpenTelemetry Bridge¶

Add OpenTelemetry as an interoperability lane, not as a replacement for Orbit's Django-native storage.

Possible milestones:

1. orbit.exporters.opentelemetry module that converts OrbitEntry objects into OTEL-like spans/events.
2. Config keys: OTEL_EXPORT_ENABLED, OTEL_EXPORT_ENDPOINT, OTEL_SERVICE_NAME, OTEL_HEADERS, OTEL_SAMPLE_RATE.
3. Map family_hash to trace_id and child entries to spans/events.
4. Map SQL/cache/http_client/job/mail/storage events to semantic attributes where stable.
5. Add GenAI/LLM attributes when the AI watcher ships.
6. Provide python manage.py orbit_export_otel --since ... for batch export.
7. Optional live export hook with strict fail-silent behavior.

Track D: AI and LLM Watcher¶

Capture AI application behavior for Django apps that call LLM providers or agent frameworks.

Initial surfaces:

• OpenAI Python SDK;
• Anthropic Python SDK;
• LangChain / LangGraph callbacks;
• LiteLLM if present;
• HTTP fallback for known provider hosts.

Events should capture only safe metadata by default:

• provider, model, operation, status;
• latency, retries, timeout/error type;
• token counts and estimated cost when available;
• tool call names, not raw arguments by default;
• prompt/completion capture disabled by default and guarded by explicit config;
• request family correlation so LLM calls appear inside the Django request timeline.

Possible config:

ORBIT_CONFIG = {
    "RECORD_AI": True,
    "AI_CAPTURE_PROMPTS": False,
    "AI_CAPTURE_COMPLETIONS": False,
    "AI_CAPTURE_TOOL_ARGS": False,
    "AI_MASK_KEYS": ["password", "token", "secret"],
}

Track E: Agent Safety Layer¶

Before Orbit becomes deeply agentic, it needs explicit data boundaries.

Milestones:

1. Central agent_safe_serialize_entry(entry) used by MCP and bundles.
2. Default field allowlists by entry type.
3. Payload size caps and deterministic truncation metadata.
4. MCP-level config: MCP_ENABLED, MCP_ALLOWED_TOOLS, MCP_DENIED_TOOLS, MCP_MAX_LIMIT, MCP_INCLUDE_PAYLOADS.
5. audit_mcp_exposure() tool.
6. Masking preview in dashboard and MCP.
7. Optional per-environment profiles: local, staging, production.

Track F: From Error to Fix Hypothesis¶

Orbit should not directly edit code. It should produce evidence-rich handoffs that coding agents can use.

Workflow:

1. Developer pastes a ticket, traceback or endpoint complaint.
2. Orbit matches it to entries, exception groups, endpoints or related logs.
3. Orbit creates an Incident Bundle.
4. Orbit ranks hypotheses and suggests repro/test plan.
5. A coding agent consumes the bundle, inspects the repo, writes tests, proposes a fix and references the evidence.
6. Orbit can later verify whether the runtime symptom disappeared.

MCP sequence example:

investigate_ticket("Users get 500 on checkout")
create_incident_bundle("ticket", "Users get 500 on checkout")
propose_fix_hypotheses(bundle_id)
propose_test_plan(bundle_id)
generate_pr_context(bundle_id)

Near-Term Priority¶

The v0.11.0 release ships endpoint investigation, daily health briefs and release risk briefs from the roadmap. The next pragmatic PR sequence:

1. Add agent_safe_serialize_entry() and make existing MCP tools use it.
2. Add investigate_request(family_hash).
3. Add investigate_exception_group(fingerprint).
4. Add create_incident_bundle(...) as on-demand JSON.
5. Add build_debug_brief(query, hours=72).
6. Add OpenTelemetry export design doc and config stub.
7. Add AI watcher behind conservative defaults.