Add AROLM target: local LLM integration with tool calling (#199)

[KrisSimon]

Migrated from GitLab MR !229 (open)
feature/199-aro-lm → main
Originally created: 2026-04-06
Author: Kris Simon
Labels: 0.10

Closes #199.

Summary

Adds a new `Sources/AROLM` Swift target that ships an `aro lm` subcommand — a local-LLM coding assistant for ARO with tool calling, per-directory context persistence, project retrieval, and an MCP bridge into the built-in `aro mcp` server.

What's in the box

Backends (auto-detected)

1. `RemoteBackend` — any OpenAI-compatible endpoint via `$ARO_LM_ENDPOINT`
2. `LlamaCppBackend` — spawns `llama-server` from llama.cpp
3. `MLXBackend` — spawns `mlx_lm.server` (Apple Silicon)

CLI surface

• `aro lm <prompt...>` — one-shot
• `aro lm` — interactive LineNoise REPL
• Slash commands: `/clean /show /tools /model /mcp /index /search /quit`
• Flags: `--model --yes --no-mcp --temperature`

Built-in tools (all path-scoped to cwd)

`read_file`, `write_file`, `edit_file`, `list_dir`, `grep`, `run_shell` (approval-gated), `aro_check`, `aro_run`, `aro_test`, `aro_build`, `parse_aro`, `list_actions`, `list_proposals`, `read_proposal`, `search_project`.

Retrieval

In-process `ProjectIndexer` + flat cosine `VectorStore` persisted at `.context.index/`, with a deterministic `HashingEmbedder` that needs no ML backend. Exposed via the `search_project` tool and `/index`/`/search` slash commands.

MCP bridge

`MCPClientBridge` spawns configured MCP servers over stdio, performs the JSON-RPC handshake, translates `tools/list` descriptors into `LMToolDescriptor`s, and registers them alongside the built-ins. `aro mcp` is bridged by default; additional servers can be declared in `.context` under `mcp_servers:`.

Context

`.context` is a human-readable YAML document in the current working directory, atomically rewritten after every turn with `0600` perms. The default system prompt is injected on first use.

Model download

`ModelManager` streams files from Hugging Face into `~/.cache/aro/models/` on first use, respects `$HF_HOME` and `$HF_TOKEN`, and prompts the user before downloading.

Tests

9 new tests in `Tests/AROLMTests` covering the context store round-trip, tool dispatch, path-guard enforcement, embedder determinism, and vector-store search. All passing.

Docs

• New proposal: `Proposals/ARO-0052-local-llm.md`
• New reference chapter: `Book/TheLanguageGuide/Chapter48-LocalLLM.md`
• New book: `Book/AROByHaluzination/` — 6 chapters + cover + metadata. Tells the story of ARO's LLM-driven genesis, the training pipeline in prose, and how to use `aro lm` day-to-day (commands, habits, automation patterns, and why running the assistant locally matters).
• Updated `README.md` Platform Support table
• Updated `CLAUDE.md` build commands

Test plan

• `swift build` clean on macOS + Linux
• `swift test --filter AROLMTests` passes
• `aro lm --help` shows the command
• `aro lm /tools` lists built-ins (requires working cwd)
• With `llama-server` available: `aro lm "hello"` downloads the model and returns a reply
• With `ARO_LM_ENDPOINT` set to a reachable OpenAI-compatible server: same
• `aro lm /index` then `aro lm /search "openapi"` returns chunks