Skip to content

README.md

Latest commit

 

History

History
124 lines (90 loc) · 8.88 KB

README.md

File metadata and controls

124 lines (90 loc) · 8.88 KB
Raw

AvaScope

Agent control plane for Avalonia apps.

AvaScope is a local-first agent tool for understanding, validating, and controlling Avalonia UI through structured CLI and MCP workflows. It helps an agent inspect running UI trees, render .axaml previews in an isolated process, capture screenshots, send narrow non-destructive input, collect diagnostics, and produce evidence artifacts without relying on unstructured screen reading.

AvaScope targets Avalonia 12 and net10.0.

What It Provides

  • Agent-oriented control loops: inspect UI state, preview variants, act through local runtime commands, capture evidence, and decide the next step from structured results.
  • Runtime inspection and narrow runtime control for bridge-enabled Avalonia apps.
  • Headless preview rendering for project-backed .axaml views.
  • Screenshot capture, focused region assertions, image diffs, and baseline checks for local evidence and CI handoff.
  • Structured diagnostics for preview readiness, build failures, bindings, resources, layout, local bridge sessions, and agent triage.
  • Explicit capability discovery so agents can gate newer CLI/MCP workflows by feature id instead of package-version guessing.
  • A command-line tool, Windows/Linux/macOS per-user install workflows, an MCP stdio server, and reusable protocol/core libraries.

Tools

  • avascope CLI: local commands for previewing, diagnostics, runtime attach, tree inspection, screenshots, input, diffs, baselines, and agent evidence workflows.
  • AvaScope.Mcp: a stdio MCP server for agent clients such as Codex, Claude, Cursor, Rider, VS Code, and Visual Studio.
  • AvaScope.Bridge: an opt-in package or external provider with a stable reflection bootstrap and automatic window registration.
  • AvaScope.PreviewHost: an isolated child process that builds/loads project views and renders previews without loading user code into the CLI or MCP server.
  • AvaScope.Protocol and AvaScope.Core: shared contracts and reusable runtime/preview plumbing.

Install From a Release

Download the current stable artifacts from the latest AvaScope release. AvaScope currently requires a compatible .NET 10 runtime.

For a diagnostics host with no AvaScope package dependency, use the separate avascope-bridge-provider.zip from the same release. Keep it outside normal app output and follow the verified loader instructions.

chmod +x avascope-linux-x64-installer
./avascope-linux-x64-installer
  • macOS Apple Silicon: download avascope-osx-arm64-installer; Intel: download avascope-osx-x64-installer. Verify its SHA-256 against release-manifest.json, then run:
chmod +x avascope-osx-<architecture>-installer
./avascope-osx-<architecture>-installer

The macOS artifacts are unsigned and unnotarized. If macOS reports quarantine after the checksum matches, remove quarantine only from the verified installer with xattr -d com.apple.quarantine avascope-osx-<architecture>-installer, or use Privacy & Security > Open Anyway. AvaScope does not bypass corporate MDM or administrator policy. The terminal installer is per-user, does not use sudo, and does not edit shell profiles; add ~/.local/bin to PATH yourself if needed.

The current Windows installer is not Authenticode-signed, so Windows SmartScreen may show an unknown-publisher warning. Verify the downloaded file against release-manifest.json on the release page. Trusted signing is tracked in issue #72.

Quick Start From Source

dotnet build AvaScope.slnx

Run a local health check:

dotnet .\src\AvaScope.Cli\bin\Debug\net10.0\avascope.dll doctor

For the first sample preview and runtime bridge workflow, see the getting started sample guide.

Per-user Windows, Linux, and macOS installers, portable executable ZIPs, and package artifacts are published from GitHub Releases when a release is cut.

Documentation

  • User guide: installation discovery, CLI/MCP usage, runtime workflows, previews and task references.
  • Agent workflow: readiness, observe/act/verify decisions, evidence review and owned cleanup.
  • Agent recipes and evaluation: executable MCP/CLI recipes, clean-project onboarding and separate conformance/agent measurements.
  • Stable surface: v1 package, protocol, CLI, MCP, exit-code, artifact, and release compatibility rules.
  • Upgrade and compatibility: version alignment, bridge-package upgrades, CLI/MCP replacement, and capability-gated client behavior.
  • Security threat model: local-only transport, bridge activation, mutation, preview, artifact, and compatibility boundaries.
  • Performance and stress audit: bounded output budgets and stress validation coverage for agent workflows.
  • Troubleshooting: attach, preview, mutation, report, and package failure triage.
  • Validation: local validation commands and release checks.
  • Visual regression CI: baseline-check artifact collection for GitHub Actions.
  • Project workflow: GitHub Issues, Milestones, labels, and Project board conventions.
  • Security policy: private vulnerability reporting and supported-version policy.
  • Contributing: contribution entry points and development policies.
  • Trademark policy: permitted use of the AvaScope name and official branding.

Safety Model

  • Runtime inspection is opt-in; host apps must explicitly activate AvaScope.Bridge.
  • Bridge discovery and control are local-only through session manifests and local named pipes.
  • Preview rendering runs user project code only inside AvaScope.PreviewHost, not inside MCP or the CLI process.
  • MCP is a thin adapter over reusable local libraries and uses structured results instead of unbounded UI payloads.
  • Runtime control is intentionally narrow, local-only, and non-destructive in the stable v1 surface. Bridge-enabled apps support bounded reversible temporary UI mutations for selected style, layout, text, class, and resource experiments, plus before/after evidence capture, session-local mutation review, and reset/close cleanup for agent review loops.

License

AvaScope-authored source code and official AvaScope release artifacts published by RolandUI, including previously published official releases, are licensed under the Apache License 2.0. See LICENSE-SCOPE.md for the exact scope of the grant, THIRD-PARTY-NOTICES.md for separately licensed dependencies, and TRADEMARKS.md for use of the project name and branding.

Project Status

AvaScope v1.1.3 is the current stable agent control-plane release. Package identities, protocol DTOs, CLI commands, MCP tools, exit codes, artifact names, and release workflow behavior are documented in docs/STABLE_SURFACE.md.

Development is tracked in GitHub Issues, Milestones, and the public AvaScope Roadmap Project board.

For hands-on agent testing, use the native QA lab: two resettable native hosts, pinned CLI/MCP/provider snapshots, independent app-state evidence and goal-based exploratory tasks.

Repository Layout

  • src/AvaScope.Protocol: transport-neutral DTOs and JSON contracts.
  • src/AvaScope.Core: local bridge and preview host clients.
  • src/AvaScope.Bridge: opt-in runtime inspection package.
  • src/AvaScope.PreviewHost: isolated preview renderer.
  • src/AvaScope.Mcp: MCP stdio adapter.
  • src/AvaScope.Cli: local command-line interface.
  • src/AvaScope.Installer: single-file Linux/macOS per-user installer host.
  • eng/installer: Windows Inno Setup wizard definition and command shim.
  • samples/AvaScope.GettingStartedApp: small Avalonia sample app.
  • tests/AvaScope.Tests: protocol, core, MCP, bridge, preview host, and CLI tests.