@leoustc/debug-agent

A local web service that records incoming bugs in a workspace's BUGS.md and runs queued, non-interactive Codex repair jobs.

The scheduler runs exactly one Codex process per workspace. A process may fix a bounded batch of pending bugs; reports received while it runs wait for the next batch.

Requirements

• Node.js 20 or newer
• Codex CLI installed and authenticated
• Each target workspace must be a Git repository

Install

npm install --global @leoustc/debug-agent

Configure

Create debug-agent.config.json outside untrusted repositories:

{
  "host": "127.0.0.1",
  "port": 7337,
  "batchDebounceMs": 1000,
  "maxBatch": 10,
  "workspaces": {
    "my-app": {
      "path": "/absolute/path/to/my-app",
      "deployment": false
    }
  }
}

Workspace paths are configured by the operator. HTTP clients may submit only a workspace ID and can never choose an arbitrary path.

For a non-loopback bind, set a token and place TLS in front of the service:

export DEBUG_AGENT_TOKEN="a-long-random-secret"

Start

debug-agent start --config ./debug-agent.config.json

Submit a bug:

curl -X POST http://127.0.0.1:7337/v1/bugs \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $DEBUG_AGENT_TOKEN" \
  -d '{
    "workspace": "my-app",
    "title": "Checkout returns 500",
    "content": "Steps to reproduce and the observed stack trace",
    "source": "production-monitor"
  }'

The response contains bugId and jobId. Query the job with:

curl http://127.0.0.1:7337/v1/jobs/JOB_ID \
  -H "authorization: Bearer $DEBUG_AGENT_TOKEN"

The health endpoint is GET /healthz.

Repair lifecycle

For each immutable batch, Debug Agent launches:

codex exec --sandbox workspace-write --json --ephemeral <repair-prompt>

Codex reads the assigned pending entries from BUGS.md, fixes and tests them, and uses the lock-aware CLI helper to update each status independently:

printf '%s\n' 'Reproduced the issue.' | \
  debug-agent bugs update --workspace . --id BUG_ID --status fixing

Typical status progression:

pending → fixing → ready_to_deploy → deployed → verified
                 ↘ fix_failed
                                    ↘ deployment_failed
                                               ↘ live_test_failed

Runtime job records and Codex output are stored under .debug-agent/ in the workspace. Add that directory to the workspace's .gitignore.

Deployment and live testing

Deployment is disabled by default. To enable it for a workspace:

1. Add an operator-owned DEBUG_WORKFLOW.md to that workspace.
2. Set its configuration entry to "deployment": true.
3. Run Debug Agent in an isolated environment with only the credentials and permissions required by that workflow.

DEBUG_WORKFLOW.md must define exact deployment steps, their success signal, an exact live test and expected result, and optionally rollback instructions. Codex deploys the combined successful batch once, then performs the live test once. It never invents missing deployment steps.

The default workspace-write sandbox is not silently escalated. A workflow that needs unavailable network or system access fails safely; broader access must be explicitly provisioned on an isolated runner.

One-shot local intake

debug-agent run \
  --config ./debug-agent.config.json \
  --workspace my-app \
  --title 'Checkout returns 500' \
  --content 'Steps to reproduce...'

This records the bug, waits for its batch to finish, and prints job state.

Library API

import {
  createDebugAgentServer,
  createDebugAgentService,
  loadConfig,
} from "@leoustc/debug-agent";

const config = await loadConfig("./debug-agent.config.json");
const service = await createDebugAgentService(config);
const server = createDebugAgentServer(service);
await server.listen();

The original DebugAgent, CheckResult, and DebugReport diagnostic-check API remains available.

Development

make install
make check
make build

Automated tests use temporary workspaces and a fake Codex adapter. They do not call the real Codex service or deploy anything.