jackwener--opencli/designs/self-repair-protocol.md

Self-Repair Protocol — Design Document

Authors: @opus0, @codex-mini0

Date: 2026-04-07

Status: Approved, updated for trace-based repair

Supersedes: designs/autofix-incident-repair.md (PR #863, deferred to Phase 2)

---

Problem Statement

When an AI agent uses opencli <site> <command> and the command fails because the site changed DOM, API, or response schema, the agent should automatically repair the adapter and retry without human intervention or pre-written spec files.

From first principles, the agent needs five things:

1. The failing command it just ran.
2. The structured error envelope from stderr.
3. The adapter source path.
4. Browser runtime evidence: actions, page state, network, console, screenshot.
5. A verify oracle: re-run the same command.

The command itself is the spec. The trace artifact is the evidence channel.

---

Design: Online Self-Repair

Core Protocol

Agent runs: opencli <site> <command> [args...]
  -> Command succeeds -> continue task
  -> Command fails ->
      1. Re-run with --trace retain-on-failure to collect a trace artifact
      2. Read trace.summaryPath from the error envelope
      3. Read adapterSourcePath from summary.md front matter
      4. Analyze: error code + failed network + console + state/action timeline -> root cause
      5. Edit the adapter file at adapterSourcePath
      6. Retry the original command
      7. If still failing -> repeat (max 3 rounds)
      8. If 3 rounds exhausted -> report failure, do not loop further

Scope Constraint

Only modify the adapter file identified by adapterSourcePath in trace summary.md front matter.

That path may be:

• clis/<site>/*.js — repo-local adapters in a source checkout
• ~/.opencli/clis/<site>/*.js — user-local adapters in npm install scenarios

The agent must use the trace summary path, not guess a repo-relative path. This matters for npm-installed users where clis/ may not be in the working directory.

Never modify:

• src/** — core runtime
• extension/** — browser extension
• autoresearch/** — research infrastructure
• tests/** — test files
• package.json, tsconfig.json — project config

When NOT to Self-Repair

Signal	Meaning	Action
Auth/login error	Not logged into site in Chrome	Tell user to log in, don't modify code
Browser bridge not connected	Extension/daemon not running	Tell user to run opencli doctor
CAPTCHA	Site requires human verification	Report, don't modify code
Rate limited / IP blocked	Not an adapter issue	Report, wait and retry later
Feature removed by site	Data no longer exists	Report, adapter may need deprecation

Retry Budget

• Max 3 repair rounds per command failure.
• Each round: trace -> edit adapter -> retry command.
• If the error is identical after a repair attempt, the fix didn't work. Try a different approach.
• After 3 rounds, stop and report what was tried.

---

Implementation

Component	Status	Location
Trace artifact output	Done	src/observation/
Error envelope trace metadata	Done	src/errors.ts, src/execution.ts
Adapter source resolution	Done	src/adapter-source.ts
AutoFix skill protocol	Done	skills/opencli-autofix/SKILL.md

Delivery Mechanism

The opencli-autofix skill is the portable self-repair protocol. Any AI agent can load this skill to get the workflow.

No separate diagnostic env var is required. The runtime has two control axes:

-v / OPENCLI_VERBOSE              human-readable logs
--trace off|on|retain-on-failure  machine-readable browser evidence artifact

---

The AutoFix Protocol

The opencli-autofix skill instructs agents:

1. When opencli <site> <command> fails, don't just report the error.
2. Re-run with --trace retain-on-failure.
3. Read the error envelope trace.summaryPath.
4. Parse summary.md front matter for adapterSourcePath.
5. Read and fix the adapter at that exact path.
6. Retry the original command.
7. If the retry passes, ask whether to file an upstream GitHub issue for jackwener/OpenCLI.
8. If approved and gh is available, file the issue using a structured summary.
9. Max 3 repair rounds, then stop.

---

Relationship to PR #863

PR #863 (spec/runner/incident framework) is not needed for Phase 1. It becomes useful later as a hardening layer:

• Phase 1: self-repair via opencli-autofix skill and trace artifacts.
• Phase 2: high-frequency failures get hardened into command specs for offline regression testing and CI.

The spec/runner framework is the asset layer. It turns ad-hoc repairs into reusable tests, but it is not the entry point.

---

Usage

No new commands. No new scripts. The agent loads the opencli-autofix skill and uses opencli normally:

# Agent runs a command as part of its task
opencli weibo hot --limit 5 -f json

# If it fails, the agent automatically:
# 1. Runs opencli weibo hot --limit 5 -f json --trace retain-on-failure 2>trace-error.yaml
# 2. Reads trace.summaryPath from trace-error.yaml
# 3. Reads adapterSourcePath from summary.md
# 4. Fixes the adapter at adapterSourcePath
# 5. Retries: opencli weibo hot --limit 5 -f json
# 6. If retry passes, asks whether to file an upstream issue
# 7. If approved, runs `gh issue create --repo jackwener/OpenCLI ...`
# 8. Continues with the task