Topolo BugFix

Public overview of BugFix, including AI-assisted bug analysis, fix generation, and Nexus-backed provider usage.

publicverified 2026-07-29bugsaiautomationgithub

What It Is

Topolo BugFix is the bug analysis and fix-automation application in the Topolo portfolio. It accepts bug reports, generates candidate fixes with AI, and can open pull requests for human review.

Architecture

BugFix runs as a worker-backed application with D1 persistence for reports, fixes, validations, and pull-request metadata. AI generation now routes through Nexus rather than calling Anthropic or OpenAI directly from the BugFix worker.

Runtime Surfaces

  • BugFix worker API
  • D1-backed bug, fix, validation, and PR data
  • Nexus gateway for AI provider access
  • GitHub for branch and PR automation

API Surface

Primary route families include:

  • /api/reports
  • /api/fixes
  • /api/admin/queue
  • /webhooks/github
  • /webhooks/validation

API Reference

BugFix currently uses curated route coverage rather than a published OpenAPI surface in system-apps/TopoloDocs.

AI Generation

BugFix uses Nexus for AI-backed fix generation and validation. Product-specific prompt logic, JSON parsing, confidence handling, and GitHub workflows remain local to BugFix, while provider invocation and usage attribution move through Nexus.

Auth and Permissions

Authenticated review and generation paths use user auth. Platform-wide BugFix admin access is reserved for Auth users whose role is super_admin in the admin organization. Background or auto-triggered AI flows use trusted service-context calls into Nexus with explicit organization and optional user attribution.

Data Ownership

Topolo Auth owns workspace identity and accessible-workspace listing. BugFix keeps an identity-only workspace mirror to scope its report rows, and owns bug reports, generated fixes, validations, and PR workflow state. Nexus owns provider access and usage attribution.

Deployments

BugFix deploys as a Cloudflare Worker. AI generation depends on Nexus gateway reachability plus a trusted Nexus service token for server-side attribution flows. Canonical gateway hosts are https://nexus.topolo.dev in development, https://nexus.stg.topolo.us in staging, and https://nexus.topolo.app in production.

Failure Modes

  • report has no organization context for Nexus attribution
  • Nexus service token or gateway configuration is missing
  • provider failure prevents fix generation or validation
  • GitHub PR creation succeeds or fails independently of AI generation

Debugging

  • confirm BugFix can reach Nexus and has a valid service token
  • verify bug reports include org_id for auto-triggered AI generation
  • inspect Nexus usage logs before checking provider dashboards
  • inspect BugFix report and fix statuses if generation fails mid-flow

Use It

Open Improve Topolo for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-bugfix --json
topolo actions --service topolo-bugfix --json
topolo actions capabilities --service topolo-bugfix --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Improve Topolo and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Reconciled the Auth-owned workspace identity mirror and current Worker deployment source through system-apps/TopoloBugFix origin/staging 53e9ed22c4be on 2026-07-29; no app-local workspace lifecycle remains.

  • Reconciled workspace verification on 2026-06-27 against system-apps/TopoloBugFix commits through 959cc6e; reviewed 133 commits since 2026-05-14, including 959cc6e Bump shared shell and onboarding packages; 20ec69d chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); fe48c2f fix(bugfix): align root wrangler split D1 bindings; 623f481 Prepare BugFix copy for translation.

  • Restricted BugFix platform-wide admin recognition to Auth super_admin users in the admin organization on 2026-04-23.

  • Verified against the current Nexus-backed BugFix generation flow on 2026-03-29