LynkMesh Autopilot Engineer

Self-healing codebase agent powered by Qwen and deterministic graph context.

LynkMesh Autopilot Engineer is an autonomous remediation workflow for PHP codebases. It reads a CI/test failure, retrieves deterministic route-controller-service-model context from a LynkMesh graph scan, asks Qwen to generate a safe patch plan, applies the patch inside a restricted boundary, runs tests, self-corrects when the first fix fails, and produces a human-reviewable remediation report.

This project is intentionally scoped as a production-minded prototype, not a production auto-deployer. It does not merge or deploy changes automatically. All fixes are prepared for maintainer review.

---

Why it matters

LLMs can generate code, but they often lack reliable understanding of a real codebase structure. LynkMesh adds deterministic codebase context: routes, controllers, services, models, impacted files, and safe patch scope. Qwen then turns that grounded context into actionable patch proposals that are verified by tests.

Execution Modes

Flag	LynkMesh context	Qwen planner	Purpose
--mock	Static JSON (runs/sample_lynkmesh_context.json)	Deterministic mock	Reproducible demos, CI, offline development
--mock-qwen	Real LynkMesh graph scan	Deterministic mock	Verify the context pipeline without API cost
(default)	Real LynkMesh graph scan	Qwen Cloud	Full production workflow

--mock exists only for deterministic demonstrations. The production execution path (default, no flags) uses Qwen Cloud through Alibaba Cloud's OpenAI-compatible API. The real Qwen integration lives in agent/qwen_client.py.

---

Quick Demo

Deterministic mock demonstration of the autonomous remediation workflow. The production execution path uses Qwen Cloud through Alibaba Cloud's OpenAI-compatible API.

---

What it demonstrates

The demo app contains two intentional issues:

1. TransactionService calls getMontlySummary() instead of getMonthlySummary().
2. TransactionModel returns amount_total, while the route contract/test expects total_amount.

The Autopilot flow demonstrates:

[MODE] MOCK | Planner: Deterministic | Context: static
failure detected
→ LynkMesh deterministic trace loaded
→ Qwen attempt 1 generated
→ patch applied inside safe boundary
→ test still fails
→ self-correction loop starts
→ Qwen attempt 2 generated
→ final test passes
→ human-reviewable report generated

Architecture

flowchart TD
    A[CI / Test Failure] --> B[Autopilot Orchestrator]
    B --> C[LynkMesh Context Adapter]
    C --> D[Qwen Cloud]
    D --> E[Risk Gate]
    E --> F[Patch Engine]
    F --> G[Test Runner]
    G --> H{Test passed?}
    H -- No --> I[Self-Correction Loop]
    I --> D
    H -- Yes --> J[Human-Reviewable Report]

Loading

---

Project structure

agent/                 Autopilot orchestration and safety components
demo_app/              Small PHP app with intentional test failures
docs/                  Architecture, demo script, and submission notes
deploy/                Docker and Alibaba Cloud deployment notes
runs/                  Sample failure/context files and runtime output
web/                   Flask dashboard for demo visualization

---

Requirements

• Python 3.10+
• PHP CLI available as php
• Qwen Cloud / Alibaba Model Studio API key for real mode
• Git and Docker are optional but recommended

Quick start: deterministic demo mode

Use this for repeatable video recording.

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

pip install -r requirements.txt
python -m agent.main --mock

Expected output:

[MODE] MOCK | Planner: Deterministic | Context: static
[DEMO RESET] restored broken baseline files=2
[TEST BEFORE] failed
[LYNKMESH CONTEXT] loaded
[QWEN PATCH] generated attempt=1
[PATCH] applied attempt=1 files=1
[TEST AFTER attempt=1] failed
[SELF-CORRECTION] starting retry
[QWEN PATCH] generated attempt=2
[PATCH] applied attempt=2 files=1
[TEST AFTER attempt=2] passed
[REPORT] runs/latest/remediation_report.md

Run with real Qwen Cloud API

Copy the example environment file:

copy .env.example .env

For Windows PowerShell, edit .env with Notepad:

notepad .env

Fill in your Qwen Cloud API key and endpoint:

MOCK_QWEN=false
QWEN_API_KEY=your_qwen_or_dashscope_key
QWEN_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
# Workspace endpoint (optional):
# QWEN_BASE_URL=https://ws-xxxxx.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-plus
QWEN_TIMEOUT_SECONDS=60

Then run:

python -m agent.main

The production execution path sends the failure log, LynkMesh deterministic graph context, retry feedback, and safe file contents to Qwen Cloud. Qwen returns a structured patch-plan JSON. The risk gate validates the response before any file is modified.

Run dashboard

After running the agent:

python web/app.py

Open:

http://127.0.0.1:8080

Useful endpoints:

GET  /health
GET  /runs/latest
POST /autopilot/run?mock=true
POST /autopilot/run?mock=false
GET  /

The dashboard includes buttons to run either deterministic mock mode or real Qwen mode. For cloud deployment proof, /health demonstrates the service is live and /autopilot/run?mock=false demonstrates Qwen-backed execution when credentials are configured.

---

Safety guardrails

The patch engine operates inside deterministic, auditable boundaries:

• Safe patch scope. Edits are restricted to files within the configured allowed_prefixes (demo_app/app/, demo_app/tests/). The risk gate rejects anything outside this boundary before the patch engine touches a file.
• Blocked paths. Sensitive files (.env, vendor/, deploy/, secrets, credentials, private keys) are rejected unconditionally.
• Edit limits. Patch plans that modify too many files are rejected — the risk gate enforces a maximum of 3 files per attempt in the demo configuration.
• Test verification. The test runner validates every patch attempt. A run is never marked as passed without a successful test execution.
• Human review. The agent generates a remediation report (runs/latest/remediation_report.md) and stops. It does not merge, deploy, or open PRs automatically.

Qwen usage

Qwen Cloud (Alibaba Cloud Model Studio) provides the reasoning layer. Qwen is used for:

• reasoning over failure logs and LynkMesh deterministic graph context;
• generating structured patch-plan JSON;
• using test failure feedback for self-correction;
• producing human-reviewable remediation summaries.

The real integration lives in agent/qwen_client.py. It calls Qwen Cloud through Alibaba Cloud's OpenAI-compatible API. The --mock flag replaces Qwen with a deterministic patch planner so the demo is reproducible without an API key — useful for:

• deterministic video demonstrations
• CI verification
• offline development

LynkMesh usage

LynkMesh provides deterministic codebase context, including:

• failure classification;
• route-controller-service-model trace;
• suspected files;
• safe patch scope;
• impacted features.

The adapter invokes LynkMesh Open directly. In real mode (python -m agent.main, no --mock) it scans the configured repository (demo_app/ by default; override with --repo) using lynkmesh pack --profile expanded + lynkmesh report, maps the failure onto the call graph, and emits a provenance-tagged context (source=lynkmesh_real). Install LynkMesh Open and ensure php is on PATH:

pip install -e ../lynkmesh-open

--mock keeps the deterministic demo using runs/sample_lynkmesh_context.json with unchanged output for video recording. --mock-qwen runs the real LynkMesh scan with deterministic (mock) Qwen — useful for verifying the real context path without API cost. If LynkMesh or PHP is unavailable in real mode, the adapter falls back to the static JSON, tagged source=static_fallback. See docs/real_lynkmesh_integration_design.md and docs/lynkmesh_capabilities.md.

Limitations

• Current demo is PHP-first.
• Current scenario focuses on route/controller/service/model remediation.
• The agent does not deploy to production.
• Generated patches require human review.
• Broader language/framework support is future work.

What's next

• GitHub PR creation.
• GitHub Actions integration.
• Laravel support.
• Better multi-file impact analysis.
• Human approval UI.
• Security scanning before patch submission.
• Incident alert ingestion.

License

MIT

Troubleshooting

See docs/troubleshooting.md for common local run issues.