# Changelog

All notable changes to AXTerminator will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.10.1] - 2026-05-25

### Fixed
- Release pipeline: the `x86_64-apple-darwin` build failed with E0463 (`can't find crate for std`) because `rust-toolchain.toml` pins the active toolchain to 1.95.0, overriding the `stable` toolchain whose rust-std target was added by the toolchain action. Added an explicit `rustup target add` step that runs inside the checkout directory so the target lands on the pinned toolchain. The v0.10.0 tag's release run failed before publishing, so v0.10.1 is the first 0.10.x release reaching crates.io, GitHub Releases, and the Homebrew tap.
- Release workflow now supports `workflow_dispatch` for validating the build matrix without consuming a tag; publish/release/homebrew jobs are guarded to run only on tag refs.

## [0.10.0] - 2026-05-25

### Added
- `axterminator-core` library crate — `AppInfo`, `WindowInfo`, `SystemContext`, `MacOsAutomation` trait, `ScreenshotResult` type (PolyForm Noncommercial license)
- Window management tools: list, focus, move, resize, minimize, close
- Interactive terminal sessions: multi-turn CLI access
- Extended system MCP tools: filesystem, processes, shell exec, memory, disk, network, power, launchd
- Power tools: file edit/search/delete, HTTP, app launch, notifications
- Enhanced TTS engine routing with Kokoro/Piper sherpa-onnx support
- Agent output integration (MIK-3286)
- `MacOsAutomation` trait for cross-module automation abstractions

### Changed
- Rust edition bumped to 2024; `rust-version` pinned to 1.95.0
- `ax_type` defaults to background mode instead of focus mode
- Toolchain pinned to Rust 1.95.0 via `rust-toolchain.toml`

### Fixed
- ApplicationServices framework linking via `build.rs` for `axterminator-core`
- Edition-2024 migration: extern blocks, unsafe ops, borrow patterns
- AppleScript brace escaping in format strings
- MCP lifecycle hardening and temp file handling
- Clippy 1.95 lints: `unnecessary_sort_by`, `manual_check`

### Internal
- Cargo.lock refreshed; resolves `--locked` incompatibility introduced by Rust 1.95.0 resolver changes
- CI action SHAs pinned for supply-chain integrity
- Dependabot: serde_json, sysinfo, clap_complete, tokio, lru, toml, cc updates

## [0.9.1] - 2026-04-16

### Changed
- `axterminator upgrade` command for seamless binary updates
- README rewritten with agent-first install as the recommended setup path

## [0.8.0] - 2026-03-22

### Breaking
- **Python package removed.** PyPI versions yanked. Use the Rust binary only.
- Crate type changed from cdylib+rlib to rlib only.
- PyO3 dependency removed entirely — binary has zero Python linkage.

### Added

#### Tools (34 total, was 19)
- `ax_query`: natural language UI questions via SceneEngine
- `ax_analyze`: UI pattern detection (14 patterns), app state inference, action suggestions
- `ax_visual_diff`: pixel-level visual regression testing
- `ax_a11y_audit`: WCAG accessibility compliance audit (1.1.1, 1.3.1, 4.1.2)
- `ax_clipboard`: read/write system clipboard
- `ax_run_script`: AppleScript/JXA execution (blocked in safe/sandboxed mode)
- `ax_session_info`: server session state
- `ax_undo`: undo last N actions via Cmd+Z
- `ax_workflow_create/step/status`: durable multi-step workflows with checkpoint/resume
- `ax_record`: interaction recording for test generation
- `ax_track_workflow`: cross-app workflow pattern detection
- `ax_test_run`: black-box desktop testing
- `ax_app_profile`: Electron app metadata (VS Code, Slack, etc.)
- `ax_browser_launch/stop`: Docker browser containers (feature: docker)

#### MCP Protocol
- **Tasks API**: tasks/list, tasks/result, tasks/cancel — async tool execution
- **Sampling**: server advertises sampling capability, ax_find_visual returns
  screenshot + sampling request when client supports it
- **Resource subscriptions**: resources/subscribe, notifications/resources/updated
- **Progress notifications**: ax_get_tree, ax_test_run, ax_workflow_step emit progress
- **Elicitation**: destructive action gate on ax_click (confirm:true required)

#### Prompts (10 total, was 4)
- `troubleshooting`: when something fails
- `app-guide`: per-app playbook (Calculator, TextEdit, Safari, Chrome, Finder, Notes)
- `automate-workflow`: durable workflow creation guidance
- `debug-ui`: debug element-not-found issues
- `cross-app-copy`: cross-application data transfer
- `analyze-app`: comprehensive UI analysis

#### Resources (6 static + 4 templates)
- `axterminator://clipboard`: system clipboard contents
- `axterminator://workflows`: cross-app workflow patterns
- `axterminator://profiles`: Electron app profiles registry
- `axterminator://app/{name}/query/{question}`: natural language scene queries

#### Security Model
- 3-tier security modes: normal/safe/sandboxed (AXTERMINATOR_SECURITY_MODE)
- App allowlist/denylist (~/.config/axterminator/security.toml)
- Rate limiting (50 rps default, configurable)
- Action audit log (~/.local/share/axterminator/audit.jsonl)

#### AI Agent Support
- `llms.txt` at repo root for machine-readable installation
- MCP instructions with progressive disclosure (compact L1 → prompts L2)

### Changed
- `ax_find`: OR semantics for simple text queries (was AND), searches
  AXTitle + AXDescription + AXValue + AXLabel + AXIdentifier
- `ax_find`: semantic fallback via SemanticFinder when exact match fails
- `ax_find`: includes healing locator in response for session persistence
- `ax_click`: auto-falls-back to CGEvent coordinate click when AXPress unsupported
- `ax_click`: response includes element bounds
- `ax_connect`: returns `app_type` (native/electron/webview) via router detection
- `ax_screenshot`: uses CGWindowListCopyWindowInfo (was broken AppleScript)
- `ax_get_tree`: optional `format="llm"` for token-optimized output
- `tree` CLI: recursion works, shows bounds, disabled state, element count
- Search scoped to windows (excludes menus and system UI)

### Fixed
- Release binary linked to absolute Python framework path (crashes on every machine)
- Standalone binary used PyO3 before Python interpreter initialized
- Simple text search required ALL attributes to match (AND instead of OR)
- AXDescription and AXValue never checked during element search
- Tree CLI only printed one level (no recursion)
- Screenshot failed on most apps (AppleScript window-id lookup broken)

### Removed
- Python package (pyproject.toml, python/ directory, 12 test files)
- PyO3 dependency
- cdylib crate type
- Python-specific CI jobs (maturin develop, pytest)
- All Python references from documentation

## [0.6.1] - 2026-03-20

### Changed
- All dependencies upgraded to latest: pyo3 0.28, axum 0.8, rand 0.10,
  core-graphics 0.25, tungstenite 0.29, sysinfo 0.38, criterion 0.8
- Zero outdated dependencies (`cargo outdated` clean)

### Fixed
- Unused variable in app.rs (CI clippy --all-features)
- CI clippy failures, unnecessary cast, unused import

## [0.6.0] - 2026-03-20

### Fixed
- Speech recognition: capture at native 48kHz sample rate (was 16kHz header
  with 48kHz data, causing garbled audio unrecognizable by SFSpeechRecognizer)
- Speech recognition: pump CFRunLoop for callback delivery (was blocking RunLoop)
- Gesture recognition: TIP vs MCP knuckle comparison with confidence filtering
- Dangerous unwrap() on missing JSON-RPC id, NaN confidence, CString user input
- 3 doctest feature-gate issues (camera, spaces)

### Security
- pyo3 0.22 → 0.24.2 (RUSTSEC-2025-0020: buffer overflow)
- lru 0.12 → 0.16.3 (RUSTSEC-2026-0002: unsoundness)
- cargo audit: 0 advisories

### Changed
- Refactored 6 modules to meet 800 LOC quality gate (tools_extended, tools,
  resources, server, elicitation, camera)
- Release pipeline: crates.io + Homebrew auto-update on tag push
- CLI binary now included in GitHub Release assets
- README badges: crates.io version/downloads, PyPI, dependency status
- Issue/PR templates updated for MCP-first workflow

## [0.5.0] - 2026-03-19

### Added
- **MCP server rewrite in Rust** — 13 files, 8163 LOC replacing Python server.py
  - 12 core tools + 18 extended tools (30 total)
  - 5 resources (apps, tree, screenshot, state, displays)
  - 4 guided prompts (test-app, navigate-to, extract-data, accessibility-audit)
  - 9 elicitation scenarios for destructive/ambiguous operations
  - Tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
  - Bearer token auth + localhost-only for HTTP transport
  - Structured MCP logging + progress notifications
- **Audio capture** (`audio` feature) — CoreAudio microphone/system capture, SFSpeechRecognizer transcription, NSSpeechSynthesizer TTS
- **Camera + gesture detection** (`camera` feature) — AVFoundation single-frame capture, Vision hand pose detection with 7 gesture types
- **Virtual desktop management** (`spaces` feature) — CGSSpace private API: list/create/move/switch/destroy
- **Multi-monitor support** — negative coordinates, Retina scaling
- Homebrew formula
- Wiki (7 pages)
- SECURITY.md, CODE_OF_CONDUCT.md, issue/PR templates

### Fixed
- Gesture recognition: TIP vs MCP knuckle comparison, confidence filtering (#25)
- Speech recognition: TCC permission request + 30s timeout (#26)
- Speech recognition: pump CFRunLoop for SFSpeechRecognizer callback delivery (#27)
- Speech recognition: capture at native 48kHz sample rate — was writing 48kHz
  data with 16kHz WAV header, causing 3x slowdown and unrecognizable audio (#27)
- Camera permission request when status undetermined
- PyO3 extension-module decoupled from CLI binary via `python-ext` feature flag
- bytes 1.11.0 integer overflow (RUSTSEC-2026-0007)
- Dangerous unwrap() on missing JSON-RPC id, NaN confidence, CString user input
- Removed Pickle virtual audio drivers intercepting default input device

### Security
- pyo3 0.22 → 0.24.2 (RUSTSEC-2025-0020: buffer overflow in PyString)
- lru 0.12 → 0.16.3 (RUSTSEC-2026-0002: IterMut unsoundness)

### Changed
- README rewritten: MCP server first, no superlatives, honest claims only
- Audio module split from 1567 LOC monolith to 5-file module (max 436 LOC)
- MCP tools_extended.rs (2640 LOC) split into 6 focused modules
- 5 additional modules split to meet 800 LOC quality gate
- camera.rs refactored to camera/ module directory
- Issue/PR templates updated for MCP-first workflow
- Gateway config points to release binary
- Published v0.5.0 to crates.io

## [0.4.0] - 2026-03-19

### Added
- **Query-based scene understanding** with encode-once keystone architecture (#4)
- **Two-stage screen intent extraction** pipeline (#5)
- **Copilot-readable state injection** (`useCopilotReadable`) (#6)
- **Persistent element references** with fingerprint-based WeakRef tracking (#7)
- **Semantic element find** and Electron DevTools Protocol integration (#8, #9)
- **Cross-app workflow intelligence** with pattern detection and automation (#10)
- **Proactive desktop copilot** with rule-based context suggestions (#11)
- **Triple understanding** and durable automation steps (#12, #16)
- **Workflow recording** and blackbox desktop testing (#13, #14)
- **Electron app skill profiles** — 5 built-in profiles + extensible registry (#15)
- **Docker browser test targets** via Neko containers for CI (#18)
- MkDocs documentation site with benchmarks
- Comprehensive tool comparison table (vs XCUITest, Appium, PyAutoGUI, Maestro)
- Python type stubs (`.pyi`) for full IDE support
- mediar-ai/terminator acknowledgement in README

### Fixed
- MCP server: VLM fallback and method calls on AXElement
- CI: formatting and skip accessibility-dependent tests
- Clippy: 10 fixes across the codebase for clean `cargo clippy` output
- 6 documentation link fixes (broken intra-doc links, stale references)

### Changed
- Updated OpenAI model references to current models (GPT-4o, GPT-5)
- README rewritten with verified benchmark numbers and factual claims
- Module-level documentation improvements with `//!` doc headers and examples
- Publication cleanup: factual claims, honest benchmarks, no superlatives

### Refactored
- Extracted `copilot_extract.rs` and `healing_match.rs` to fix LOC violations
- Registered new modules in `lib.rs`

## [0.3.2] - 2026-03-18

### Added
- Python type stubs (`.pyi`) for full IDE support — autocomplete, type checking, and inline documentation for all Rust-backed classes (`AXApp`, `AXElement`, `HealingConfig`, `ActionMode`) and module-level functions
- Dead code annotations (`#[allow(dead_code)]`) for planned XPath healing strategy infrastructure in `healing_match.rs`, `router.rs`, `sync.rs`, and `accessibility.rs`

### Fixed
- **Clippy cleanup**: 10 fixes across the codebase — resolved all warnings for clean `cargo clippy` output
- 6 documentation link fixes across module docs (broken intra-doc links, stale references)

### Changed
- Module-level documentation improvements — all public modules now have `//!` doc headers with examples
- Docker browser test targets via Neko containers for CI (#18)
- Electron app skill profiles — 5 built-in profiles + registry (#15)
- Proactive desktop copilot with rule-based context suggestions (#11)
- Cross-app workflow intelligence with pattern detection (#10)
- Workflow recording and blackbox desktop testing (#13, #14)
- Query-based scene understanding with encode-once keystone (#4)
- Semantic element find and Electron DevTools Protocol (#8, #9)
- Triple understanding and durable automation steps (#12, #16)
- Persistent element references with fingerprint-based WeakRef tracking (#7)

## [0.3.1] - 2026-02-01

### Added
- Real-world examples (Safari, Finder, TextEdit workflows)
- Chrome recorder browser extension

## [0.3.0] - 2026-01-19

### Added
- CLI tool (`axterminator inspect`, `axterminator tree`, `axterminator record`)
- Action recording and playback
- pytest plugin (`pytest-axterminator`)
- Ollama local VLM backend
- MCP server for Claude Code integration

## [0.2.1] - 2026-01-18

### Added
- PyPI publishing workflow
- XPC sync module
- API documentation

## [0.2.0] - 2026-01-17

### Added
- Gemini VLM backend
- VLM examples
- MLX/Claude/GPT-4V visual element detection

## [0.1.0] - 2026-01-10

### Added
- Initial release
- Background GUI testing (no focus stealing)
- 7-strategy self-healing locators
- Python bindings via PyO3
- macOS Accessibility API integration
- ~379 us element access (measured on M1 MacBook Pro)
