# RepoRescue — Verified Code Rescue

**Paste broken Python code or a reviewed allow-listed public Python GitHub repository. RepoRescue explains it, generates a minimal repair, runs before-and-after verification, and reports exactly what the evidence proves.**

RepoRescue is not another “maybe try this” coding chatbot. Its differentiator is a verification protocol:

```text
understand intent → reproduce failure → generate minimal fix → run the same case again → grade the evidence
```

The product serves beginners through one low-friction entry point while keeping repository reproduction as the advanced mode:

| Mode | User provides | RepoRescue returns |
|---|---|---|
| Quick code rescue | A snippet, function, error, or assignment | Plain-language cause, repaired code, before/after run evidence |
| Project rescue | A reviewed allow-listed public Python GitHub repository and optional issue description | Commit-pinned failure, generated source repair, same-command verification, patch and evidence bundle |

Direct file/notebook upload is a planned mode, not a current backend capability.

On a deployed service, users do not install or start Docker and do not confirm
an isolation mode in chat. They submit the code or an allowed repository URL;
the backend worker owns isolation and execution. The Docker setup commands below
are for administrators and local developers, not the hosted user flow. If the
worker is unavailable, execution fails closed instead of running code on the host.

## Why it is different

- **Generated repair, not a checklist:** the agent produces the candidate code.
- **Before/after proof:** a fix is “verified” only when the original fails and the repaired version passes the same stated case.
- **Beginner-first result:** users see the cause, change, and outcome before technical logs.
- **Scoped claims:** snippet execution, repository tests, official demos, and paper metrics are different evidence levels.
- **Portable core:** the same MCP tools can power XFYun Agent, OpenClaw, Codex, or another agent shell.

## Backend repair architecture

```text
reviewed allow-listed public Python GitHub URL + issue
        │
        ▼
commit-pinned temporary checkout
        │
        ▼
Docker/managed verifier ── records failing command, exit code and logs
        │
        ├── OpenAI Repair Agent (server-managed, API key path)
        │
        └── Host Repair Agent (prepare + submit proposal, no model API key in backend)
        │
        ▼
safe patch application ── blocks traversal, test edits, new files and Git metadata
        │
        ▼
same-command verifier ── retries up to the configured attempt limit
        │
        ▼
repair.patch + evidence.json + report.md
```

## Interview demo — one command, no model API key or Docker

From PowerShell in the repository root:

```powershell
.\demo.ps1
```

On Windows, `demo.cmd` can also be double-clicked.

The script creates or reuses `.venv`, installs the project, and runs a seeded broken calculator through the real orchestration path. The original test exits `1`, the Repair Agent changes `calculator.py`, the exact same command exits `0`, and a timestamped evidence bundle is written under `artifacts/`.

This deterministic demo is intentionally limited to the bundled trusted project, so the repair run itself needs neither Docker, network access nor model credentials. A first-time setup may still need package access to install the Python dependencies. Reviewed allow-listed public Python GitHub repositories use one of the isolated paths below.

## Quick start: hosted Node MCP

The hosted launcher uses a fresh child-process CPython WebAssembly worker for bounded snippet execution. It runs the original and candidate in two separate workers **sequentially**, so a 256 MB hosted instance does not keep two Pyodide runtimes resident at once. The revisions still share no interpreter state, and each worker retains the same hard wall-clock, V8 heap, protocol, and output limits. Because the wall-clock limit applies independently to both workers, the MCP client timeout must allow two worker budgets plus cold-start overhead (about 12 seconds plus overhead with the 6000 ms default). Node never executes repository code in its own hosted container. The `platform` toolset can instead dispatch a bound request to this repository's trusted GitHub Actions workflow, where the Python v0.4 backend uses Docker isolation.

```powershell
npm install
npm test
npm run benchmark
node .\stdio-server.mjs
node .\platform-entry.mjs
```

For compatibility the default Node launcher keeps the legacy four-tool surface, but `reproduce_python_project` never clones or executes repository code there. Set `REPO_RESCUE_NODE_TOOLSET=snippet` for snippet-only hosting. The dedicated `repo-rescue-mcp-platform` bin is the competition entrypoint: it unconditionally fixes the reviewed toolset, control repository, workflow, protected ref, two-repository allow-list, rates, timeouts, and snippet budget in code. Discovery then contains exactly `rescue_python_snippet`, `start_prepare_github_repair`, `get_repair_job`, and `start_verify_github_patch`, while direct calls to hidden legacy tools fail closed.

### XFYun Agent repair through an authenticated HTTP gateway

The current integration candidate uses four XFYun personal HTTP plugins. A single-replica Node gateway on Railway hosts the reviewed `platform` stdio worker; the long, untrusted repository run executes on an Ubuntu GitHub runner. Two real autonomous repository repairs passed backend artifact audits on 2026-09-10, but the model's final transcription altered hashes or patch text. The new delivery candidate returns a signed, read-only receipt with original artifact downloads. Its platform validation and publication are still pending. See [deployment evidence](docs/external-mcp-deployment.md), [original artifact delivery](docs/artifact-receipts.md), and the [current integration checklist](docs/xfyun-http-agent-acceptance.md).

```text
XFYun model → authenticated HTTP plugin → Node platform worker → GitHub workflow_dispatch
             → pinned workflow checkout → fixed verifier Docker image
             → Python v0.4 prepare/verify → bound artifact ZIP
XFYun model ← rescue_poll HTTP plugin ← result.json + repair.patch + evidence.json + report.md
```

Generic self-hosting can configure the standard launcher with administrator-owned values; none of them is accepted as a tool argument:

```text
REPO_RESCUE_NODE_TOOLSET=platform
REPO_RESCUE_GITHUB_TOKEN=<fine-grained token>
REPO_RESCUE_ACTIONS_REPOSITORY=wenjieding327/repo-rescue-mcp
REPO_RESCUE_ACTIONS_WORKFLOW=repo-rescue-actions-bridge.yml
REPO_RESCUE_ACTIONS_REF=<protected branch containing the reviewed workflow>
REPO_RESCUE_ALLOWED_REPOS=wenjieding327/repo-rescue-canary,wenjieding327/repo-rescue-mcp
```

For the current candidate, deploy `http-sse-server.mjs` using `Dockerfile.railway`, inject separate gateway and repository credentials in Railway, and configure the four XFYun plugins with Service/Header authentication. XFYun receives only the dedicated gateway credential; the GitHub credential stays in Railway. Inputs use JSON Body, not Query. HTTP 200 and `is_error=false` are transport results, never repair verdicts. See [the exact plugin mapping and acceptance gates](docs/xfyun-http-agent-acceptance.md).

The earlier XFYun-hosted MCP alternative is retained for recovery, not claimed operational: command `npx`, arguments `-y https://github.com/wenjieding327/repo-rescue-mcp/releases/download/v0.4.1-xfyun.1/repo-rescue-mcp-platform-0.4.1-xfyun.1.tgz`. `npm run pack:xfyun` and `npm run verify:xfyun` still audit and execute the single-bin archive locally. Local package success does not prove XFYun runner startup. Do not rebind or retransmit credentials merely to retry this historical alternative.

The fine-grained token is restricted to the one bridge repository with **Actions read/write**; RepoRescue does not need Contents, Workflows, Administration, or a model API key on that token. The Node and workflow allow-lists must be identical. The trusted workflow has its own fixed allow-list, builds `repo-rescue-python:3.11`, clears `GITHUB_TOKEN`/`GH_TOKEN` for the controller step, and never adds a credential to the untrusted Docker container.

Dispatch payloads are gzip+base64 but are not trusted: both sides enforce 55,000 encoded and expanded bytes, at most three replacements, and 12,000 characters per replacement. Active work defaults to one job (matching the workflow's global single concurrency), three starts per minute, and twelve starts per hour. Every start receives a private in-process `job_id`; the separate 256-bit `request_id` appears in the public Actions run/artifact only as a correlation nonce and is never accepted as authorization. A timed-out dispatch POST is discovered by that exact nonce and is never implicitly re-dispatched. Verification additionally requires the still-live private `preparation_job_id`, an exact repository/commit/baseline match, and one-time consumption of that preparation capability; an idempotent retry of the same verify call returns its already-started verify job. Polling checks workflow/run/ref/head SHA, request ID, payload SHA, artifact ID/digest, ZIP layout, patch SHA, and evidence fields. A successful verify returns the real bounded patch, evidence JSON, and report text under `job.result.github_actions.artifact_contents`.

This competition bridge remains intentionally limited to reviewed **public Python repositories**. Do not put credentials, private source, personal data, or secrets in the issue text or proposed patch: workflow inputs and one-day artifacts live in the team's GitHub Actions control repository. The hosted process keeps job capabilities in memory; if that process restarts, an already-running GitHub job may finish but the old `job_id` is no longer pollable. The Agent must start a fresh prepare chain rather than reuse an orphaned commit/baseline. A commercial service should persist job mappings in a database and use a GitHub App installation token.

Release operators can run `node scripts/live_actions_bridge_smoke.mjs` after setting the reviewed environment variables and a process-only `REPO_RESCUE_GITHUB_TOKEN`. The smoke performs a real prepare→verify chain against the team canary and exits non-zero unless the Docker baseline fails, the same pytest command passes after one source-only replacement, all three evidence texts are returned, and their hashes agree. Set `REPO_RESCUE_ACTIONS_EXPECTED_HEAD_SHA` to the frozen 40-character bridge commit for an additional release-ref assertion. Never put the token on the command line or in a tracked `.env` file.

### `rescue_python_snippet`

Supply original code and the AI-generated candidate. Optional cases provide stdin and expected stdout. Without expected output, RepoRescue can prove only that the candidate ran; it will not label the change a verified fix.

```json
{
  "original_code": "numbers = [1, 2, 3]\nprint(numbers[3])",
  "candidate_code": "numbers = [1, 2, 3]\nprint(numbers[-1])",
  "test_cases": [
    {"name": "last item", "stdin": "", "expected_stdout": "3"}
  ]
}
```

The response records the original `IndexError`, the repaired output, case-level status, and a scoped `S2`/`L1_SNIPPET_EXECUTION` result. It never claims a whole project or paper was reproduced from this snippet run.

`npm run benchmark` exercises fourteen deterministic success and rejection cases, including index, type, syntax, zero-division, missing-key, runaway-loop, unsafe-import, incorrect-candidate, already-passing, over-limit, missing-oracle, deterministic-random, serializer-corruption and private-runtime-escape inputs. This benchmarks the execution/verdict backend; it does not measure how often an LLM generates the correct candidate repair.

## Full repository Repair Agent

The Python backend provides repository inspection, container-backed reproduction, repository repair orchestration, verification and artifact output:

```powershell
py -3.11 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev,agent]"
.venv\Scripts\python -m pytest
docker build -f sandbox/Dockerfile.python311 -t repo-rescue-python:3.11 .

$env:OPENAI_API_KEY="your-api-key"
$env:REPO_RESCUE_ALLOWED_REPOS="owner/broken-repository"
.venv\Scripts\repo-rescue repair `
  https://github.com/owner/broken-repository `
  --issue "describe the observed failure" `
  --artifacts .\artifacts
```

The repair command uses the [OpenAI Responses API](https://developers.openai.com/api/docs/guides/latest-model). `REPO_RESCUE_OPENAI_MODEL` selects the model and defaults to `gpt-5.6-terra`. The repository must be public and explicitly allow-listed; arbitrary shell commands are never accepted.

To expose the same workflow as MCP, run `.venv\Scripts\repo-rescue-mcp`. The Streamable HTTP endpoint defaults to `http://localhost:8000/mcp`; set `REPO_RESCUE_TRANSPORT=stdio` for a command-based host or `REPO_RESCUE_TRANSPORT=sse` for a legacy SSE client. Direct SSE uses the verified root `/sse` and `/messages/` routes. If a public URL needs a path prefix, add it in a reverse proxy rather than setting a FastMCP runtime mount path.

The root `Dockerfile` packages the MCP API and trusted interview Demo; it does not embed a Docker daemon. Run full repository repair from a host/worker that can reach the separately built `repo-rescue-python:3.11` verifier image. Do not expose a privileged Docker socket to anonymous callers.

### Automatic test discovery

The trusted pytest worker extends default discovery to `test.py`, `tests.py`
(including `src/tests.py`), and `*_tests.py`, alongside pytest's default names.
It does not supply a manually selected file path or replace `testpaths`.
An explicit `python_files` setting or `-o python_files=...` override remains
authoritative, including an empty setting or an explicit copy of the defaults.
A valid `tox.ini` is a pytest signal only if it contains a `[pytest]` section;
tox commands are never executed automatically. Damaged or unreadable tox
configurations retain pytest verification instead of a compile-only fallback.

Results record `pytest_discovery_policy=project-config-or-extended-defaults-v1`.
The same policy is used before and after patching. A zero-test run still fails
verification, and the additional test filenames are protected against repair
edits. This supports conventional Python layouts, not arbitrary test frameworks
or arbitrary unreviewed repositories. See pytest's official documentation on
[configuration](https://docs.pytest.org/en/stable/reference/customize.html) and
[test discovery](https://docs.pytest.org/en/stable/example/pythoncollection.html).

### API-key-free host-agent repair

An agent platform such as XFYun can use its own model as the Repair Agent, so the user and RepoRescue repair backend do not need a separate model API key. The private platform administrator still supplies the least-privilege GitHub Actions credential described above:

```text
prepare_github_repair(repo_url)
  → pinned commit + real baseline + baseline_sha256 + bounded untrusted source/config context
host model generates complete-file replacements
verify_github_patch(repo_url, expected_commit, expected_baseline_sha256, changes)
  → fresh checkout + baseline hash match + protected patch + same-command re-verification
```

Agent platforms with short tool-call deadlines should use the asynchronous equivalents:

```text
start_prepare_github_repair(repo_url) → job_id
get_repair_job(job_id, wait_seconds<=20) → preparation result
host model generates complete-file replacements
start_verify_github_patch(...) → job_id
get_repair_job(job_id, wait_seconds<=20) → verified result
```

The actual wire shape is `start.job.job_id`, followed by `poll.job.terminal/status/result`; preparation lives at `job.result.preparation` and the final verdict at `job.result.repair.verified_repair`. The hosted Node `platform` variant adds a required `preparation_job_id` to its verify tool and consumes that capability once; the direct Python MCP signature remains unchanged. A job status of `succeeded` means only that the backend operation returned—not that a repair was verified. Jobs use unguessable lookup IDs, bounded queues/rates, and finite in-memory TTLs.

The in-memory job store is deliberately a single-instance competition/demo design: run exactly one application process and one replica so a start and its polls reach the same store. Jobs do not survive restart or rolling deployment. A commercial multi-worker or multi-replica service must move the queue and results to Redis or a database, authenticate callers, enforce per-tenant rate limits, and terminate TLS at a gateway.

This path still requires an isolated execution backend. Local untrusted repositories use Docker. A managed host may use `REPO_RESCUE_EXECUTION_BACKEND=direct` only when the whole service already runs inside a disposable, resource-limited container and the repository is explicitly allow-listed. If dependency installation prevents the baseline pytest run, a later passing suite is reported as `repair_tests_passed_uncompared`, not `verified_repair`, because the original test coverage could not be measured.

## Repository tools

### `inspect_github_project`

Read-only inspection of a public repository. Returns the exact commit, bounded file tree, Python manifests, dependency declarations, version hints, risks, entry points, and suggested verification commands. The execution allow-list is checked before any reproduction or repair run, not before read-only inspection.

### `reproduce_python_project`

Runs a fixed verification scope for an explicitly allow-listed Python repository and returns the actual command, install/execution exit codes, duration, bounded logs, backend, and evidence boundary.

### `repair_github_project`

Runs the full repository loop: commit-pinned clone, Docker baseline, bounded Repair Agent proposal, protected source replacement, identical-command verification, retry, and durable evidence artifacts. It never pushes or opens a pull request.

### `prepare_github_repair` + `verify_github_patch`

Runs the same evidence protocol with the surrounding agent host as the Repair Agent. Preparation is never called a success. The second tool checks both the 40-character commit and preparation baseline hash, applies only bounded replacements to existing allowed files, reruns dependency analysis and installation, and reports a repair only when the exact verifier command passes. A repair may change versions of existing dependency names; adding a new distribution requires explicit administrator approval through `REPO_RESCUE_ALLOWED_ADDITIONAL_DEPENDENCIES`.

### `start_prepare_github_repair` + `start_verify_github_patch` + `get_repair_job`

Runs the same preparation and verification operations through a bounded background queue for agent platforms that disconnect long synchronous calls. Polling never restarts an operation. Only the terminal job result—and ultimately `verified_repair=true`—can support a repair claim.

### `run_interview_demo`

Runs the deterministic end-to-end demonstration through MCP without Docker or an API key. This is the safest live interview entry point.

### `get_repair_artifact`

Returns bounded chunks of `repair.patch`, `report.md`, or `evidence.json` using a generated run ID instead of exposing server filesystem paths.

### `windows_environment_probe`

Returns a copy-paste PowerShell probe. It never claims to read a user's computer automatically and does not change the machine.

## Evidence levels

- **S1:** snippet executed.
- **S2:** original snippet failed and repaired snippet passed the same case.
- **P1:** repository and commit inspected; no execution claim.
- **P2:** dependencies resolved.
- **P3:** named repository test scope executed with recorded exit code.
- **P4:** documented official demo reproduced.
- **P5:** paper metric reproduced under a stated dataset, configuration, seed, and hardware boundary.

The archived competition deployment has evidence for **S2** on safe Python snippets and **P3 for the named Click core smoke scope**. The source tree also has a deterministic 14/14 snippet backend benchmark and a host-agent path that needs no separate model API key. The private platform administrator still configures a least-privilege GitHub Actions credential. These source capabilities must be redeployed and retested on the public Agent before they are described as live. None of them claims P4 or P5.

## Verified Code Rescue Skill

[`skills/verified-code-rescue/SKILL.md`](skills/verified-code-rescue/SKILL.md) packages the distinctive orchestration protocol for agent hosts. It routes snippets, files, and repositories; requires before/after evidence; grades the claim scope; and produces a beginner-readable answer before technical details.

This Skill is intentionally not a generic coding prompt. Its reusable value is the truth-preserving rescue workflow.

## Safety boundary

- Snippet rescue limits source size and case count, permits only a small safe standard-library import set, rejects filesystem/process/network capabilities, and applies a deterministic execution budget.
- Repository execution remains allow-listed and constrained.
- Model output can replace only exact paths from the initial bounded source/config inventory; test trees and their helpers, `conftest.py`, pytest discovery/execution settings, path aliases, traversal, symlinks and Git metadata are rejected. New dependency distribution names are denied by default, pytest plugin autoload is disabled, and a trusted parent controller parses worker-produced JUnit evidence before accepting a pytest result.
- A repair is verified only when the pinned original fails and the modified checkout passes the exact same recorded command.
- Repository execution is isolated as untrusted code, but semantic pytest evidence assumes an administrator-allow-listed test harness is not deliberately designed to spoof pytest internals; production exposure to hostile repositories requires a stronger verifier trust boundary.
- The service does not read a user's computer, accept arbitrary shell commands, or execute private repositories.
- Public production should move untrusted repositories to gVisor or Firecracker, authenticate and rate-limit callers, scan archives, restrict outbound installation traffic, and expire stored source and logs.

## Portfolio summary

> Built a backend Repair Agent that accepts a reviewed allow-listed public Python GitHub repository, creates a commit-pinned isolated checkout, reproduces a real failure, generates and safely applies a bounded source repair, reruns the exact same verifier, and emits a patch plus machine-readable and human-readable evidence. Exposed the loop through CLI and MCP while preventing test tampering and unverified success claims.

## Roadmap

- File and notebook upload with focused test generation.
- Broader dependency-conflict and lockfile strategies beyond existing manifest replacement.
- Web job dashboard and downloadable artifact bundle.
- Official-demo (`P4`) benchmark cases beyond the bundled interview fixture.
- Optional GitHub Issue/PR output after explicit user confirmation.