feat(core): Debug mode

[neriousy]

What does this PR do?

PR Summary: Debug Mode Feature

This PR introduces a new Debug Agent Mode that enables evidence-based debugging through structured instrumentation, log analysis, and a guided reproduction workflow.

HEAVILY INSPIRED FROM CURSOR DEBUG MODE

Overview

• Adds a dedicated debug agent mode alongside existing modes (e.g. build, explore)
• Enforces a disciplined, multi-phase debugging workflow
• Introduces infrastructure for structured debug logs and reproduction steps
• Integrates debugging flows into the API, UI, and SDK

---

Key Features

1. New Debug Agent Mode

• Adds a new debug agent mode
• Description: “Evidence-based debugging mode. Use this to generate hypotheses, add runtime instrumentation, analyze logs, and only then implement fixes.”

---

2. Structured Debug Workflow

The debug prompt (packages/opencode/src/agent/prompt/debug.txt) defines a 7-phase workflow:

1. Generate testable hypotheses
2. Add instrumentation logs (3–8 logs)
3. Reproduce the issue with log clearing
4. Analyze logs (NDJSON format)
5. Implement fixes (only with supporting evidence)
6. Verify with before/after comparison
7. Cleanup after confirmation

---

3. Debug Infrastructure

• Debug module (src/debug/index.ts)

  • Log ingestion
  • Config injection
  • File management

• Debug config injection

  • Automatically injects a <debug_config> block into system prompts when using the debug agent

• Log format

  • NDJSON (one JSON object per line)

  • Required fields:

    • sessionId
    • runId
    • hypothesisId
    • location
    • message
    • data
    • timestamp

---

4. Reproduction Steps System

• New reproduction steps request/response system (src/debug/repro.ts)

• TUI component (reproduction-steps.tsx) for user interaction

• Supported actions:

  • proceed
  • fixed
  • skipped

• Integrated into the session UI with keyboard navigation

---

5. API Endpoints

• POST /ingest/:sessionId Ingest debug logs and append them to .opencode/debug.log
• GET /reproduction-steps List pending reproduction requests
• POST /reproduction-steps/:requestID/reply Reply to a reproduction prompt
• POST /reproduction-steps/:requestID/reject Reject a reproduction prompt

---

6. UI Integration

• Reproduction steps prompt component with visual indicators
• Integrated into the session view with proper priority (shown after permissions and questions)
• Keyboard shortcuts for navigation and confirmation

---

7. SDK Updates

• Regenerated JavaScript SDK to include new endpoints

• Added:

  • Debug client
  • ReproductionSteps client

• Updated type definitions for all new APIs

---

8. Testing

• Debug ingestion tests (debug-ingest.test.ts)
• System prompt injection tests (debug-system-injection.test.ts)
• Reproduction steps route tests (reproduction-steps.test.ts)

---

Technical Details

• Logs are written to .opencode/debug.log in the worktree root
• Instrumentation uses HTTP POST requests to the ingest endpoint (no direct file writes)
• Debug logs are isolated per session
• Error handling ensures logging failures do not break the application

---

How did you verify your code works?

https://github.com/user-attachments/assets/241d9628-ad32-48e8-9e49-a8e44cf9333b