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

---

How did you verify your code works?

2026-01-17.01-15-28.mp4

[github-actions]

Hey! Your PR title Feat(core): Debug mode doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[neriousy]

If you got any tips and tricks would be nice. Didn't have a chance to test out with the more popular models like opus / gemini cause I ran out of interference tokens