@miller-tech/uap 1.40.0 → 1.41.0

package/docs/guides/LOCAL_MODELS.md

@@ -0,0 +1,148 @@
+# Running UAP Against Local Models
+
+> UAP v1.40.0
+
+UAP can drive its coding/convergence loop against **local models** served by
+[llama.cpp](https://github.com/ggml-org/llama.cpp) instead of a hosted API.
+This keeps inference on your own hardware (zero per-token cost) and works with
+quantized open-weight models such as Qwen 3.x.
+
+There are two endpoint shapes involved, and it matters which client speaks
+which protocol:
+
+- **`uap deliver`** talks the **OpenAI-compatible** Chat Completions API
+  (`POST /v1/chat/completions`). It points directly at llama.cpp's OpenAI
+  endpoint (commonly `:8080/v1`) — no translation proxy is needed for UAP's own
+  loop. See
+  [`src/models/openai-compat-client.ts`](../../src/models/openai-compat-client.ts).
+- **Anthropic-protocol clients** (e.g. Claude Code) speak the **Anthropic
+  Messages API**. When llama.cpp serves the Anthropic protocol natively, those
+  clients can point straight at the local port. Where native Anthropic serving
+  is not available, the bundled `uap-anthropic-proxy` translates Anthropic
+  requests into OpenAI requests for llama.cpp. Prefer the direct, native path
+  when you have it.
+
+## The model presets
+
+`uap deliver` selects a model by **preset id**. Presets are defined in
+[`src/models/types.ts`](../../src/models/types.ts) (`ModelPresets`). The default
+local preset is `qwen35-a3b`:
+
+```jsonc
+// qwen35-a3b (excerpt)
+{
+  "provider": "custom",
+  "apiModel": "qwen35-a3b-iq4xs",
+  "endpoint": "http://192.168.1.165:8080/v1",  // llama.cpp OpenAI endpoint
+  "maxContextTokens": 262144
+}
+```
+
+The endpoint is the llama.cpp server's OpenAI-compatible base. Adjust it for
+your host (for example `http://localhost:8080/v1`) by overriding the endpoint
+(see below) or editing the preset.
+
+> The exact host/IP in the shipped preset is environment-specific. Point it at
+> wherever your llama.cpp server is listening.
+
+## Serving a local model
+
+Start llama.cpp's `llama-server` listening on an OpenAI-compatible port
+(`:8080` by default in the helper scripts). A continuity helper for serving is
+included at
+[`scripts/run-llama-server-continuity.sh`](../../scripts/run-llama-server-continuity.sh);
+it wraps `llama-server` with `--host`, `--port` (default `8080`), `--model`,
+and an optional `--chat-template-file`. Models with a custom chat format need
+the correct template applied.
+
+UAP ships several helpers around local serving (registered as bins in
+`package.json`):
+
+- **`llama-optimize`** — generates optimal `llama.cpp` startup parameters
+  (quantization profile, KV-cache quant, flash attention, speculative
+  decoding, etc.) for Qwen 3.x-class models on 16GB/24GB VRAM. Source:
+  [`src/bin/llama-server-optimize.ts`](../../src/bin/llama-server-optimize.ts).
+- **`uap-template-verify`** — model-agnostic chat-template finder/verifier;
+  validates Jinja2 syntax, renders test data, and checks tool-call format
+  support. Source:
+  [`tools/agents/scripts/chat_template_verifier.py`](../../tools/agents/scripts/chat_template_verifier.py).
+- **`uap-anthropic-proxy`** — Anthropic→OpenAI translation proxy for clients
+  that only speak the Anthropic Messages API. Source:
+  [`tools/agents/scripts/anthropic_proxy.py`](../../tools/agents/scripts/anthropic_proxy.py).
+  It reads `LLAMA_CPP_BASE` (upstream OpenAI endpoint) and `PROXY_PORT` from the
+  environment. Use this only when a client can't reach a native Anthropic
+  endpoint.
+
+## Running the convergence loop locally
+
+`uap deliver` iterates a model through execute → apply → verify → feedback until
+real completion gates pass. To run it against a local model, pass the preset:
+
+```bash
+uap deliver "fix the failing build" --model qwen35-a3b
+```
+
+Because `qwen35-a3b` is the default preset, you can also omit `--model` (or set
+`UAP_DELIVER_MODEL`):
+
+```bash
+export UAP_DELIVER_MODEL=qwen35-a3b
+uap deliver "add input validation to the parser"
+```
+
+### Pointing at your own server
+
+Override the endpoint without touching the preset:
+
+```bash
+uap deliver "refactor the auth module" \
+  --model qwen35-a3b \
+  --endpoint http://localhost:8080/v1
+```
+
+The endpoint must be an OpenAI-compatible `/v1` base. If no endpoint is set on
+the preset or the flag, the client falls back to `UAP_INFERENCE_ENDPOINT`, then
+to `http://localhost:4000/v1`.
+
+### Useful `uap deliver` options
+
+| Option              | Meaning |
+| ------------------- | ------- |
+| `-m, --model <preset>` | Model preset id (default `$UAP_DELIVER_MODEL` or `qwen35-a3b`) |
+| `--endpoint <url>`  | Override the model endpoint (OpenAI-compatible `/v1`) |
+| `--temperature <t>` | Sampling temperature (default: execution-profile value) |
+| `--max-turns <n>`   | Maximum execute→verify iterations (default 5) |
+| `--gates <ids>`     | Restrict to a subset of gates (`build,typecheck,test,lint`) |
+| `--escalate` / `--escalate-model <preset>` | On stagnation, escalate to a stronger model preset (default `$UAP_ESCALATE_MODEL`) |
+| `--coordinate`      | Register the run with the coordination layer (announce, heartbeat, overlap detection) |
+| `--deploy`          | On success, queue a commit of applied files into the deploy batcher |
+| `--dry-run`         | Show detected gates and plan without calling the model |
+
+A common local pattern is a cheap local executor that escalates to a hosted
+model only when it stalls:
+
+```bash
+uap deliver "implement the retry logic" \
+  --model qwen35-a3b \
+  --escalate --escalate-model sonnet-4.6
+```
+
+## Connecting Claude Code (or other Anthropic clients)
+
+If your llama.cpp server exposes the Anthropic Messages API natively, point the
+Anthropic client at that local port directly — this is the preferred path.
+
+Otherwise, run the translation proxy in front of llama.cpp:
+
+```bash
+LLAMA_CPP_BASE=http://localhost:8080/v1 PROXY_PORT=4000 uap-anthropic-proxy
+```
+
+The client then talks the Anthropic protocol to the proxy, which forwards
+OpenAI requests to llama.cpp. The proxy supports streaming and tool-call
+translation.
+
+## Related
+
+- [Deploy Batching](./DEPLOY_BATCHING.md) — what `uap deliver --deploy` queues.
+- [Coordination](./COORDINATION.md) — what `uap deliver --coordinate` registers.

package/docs/guides/MCP_ROUTER.md

@@ -0,0 +1,195 @@
+# MCP Router
+
+> UAP v1.40.0
+
+The MCP Router is a token-optimizing proxy that sits between an AI harness and
+its MCP tool servers. It is implemented as 11 modules under
+[`src/mcp-router/`](../../src/mcp-router/) and exposed through the
+`uap mcp-router` CLI.
+
+## The problem: tool-output token bloat
+
+When an agent calls an MCP tool, the *entire* tool result is injected into the
+model's context window. A single `read_file`, search, or API call can return tens
+of kilobytes of mostly-irrelevant text. Across a session this dominates token
+spend and crowds out useful context.
+
+The router solves this by **compressing tool output before it reaches the model**,
+returning only the parts the agent actually needs. In practice this yields **up
+to 98% token reduction** on large outputs.
+
+## Compression strategy
+
+Every tool result passes through the output compressor
+([`output-compressor.ts`](../../src/mcp-router/output-compressor.ts)), which picks
+a strategy based on output size and whether the call supplied an *intent*:
+
+| Output size | Strategy | Method |
+|-------------|----------|--------|
+| ≤ 5 KB | **Pass through** unchanged | `passthrough` |
+| 5–10 KB | **Head + tail** smart truncation | `truncated` |
+| ≥ 10 KB **with intent** | **FTS5 index-then-search** — return only matching snippets | `indexed` |
+| ≥ 10 KB without intent | Head + tail smart truncation | `truncated` |
+
+The exact thresholds are `5120` bytes (truncation) and `10240` bytes
+(auto-indexing).
+
+### Intent-driven FTS5 search
+
+When an output is large and the agent describes what it is looking for (an
+`intent`), the compressor:
+
+1. **Chunks** the content by structure — markdown headings first, then
+   blank-line paragraphs, then fixed-size line blocks as a fallback.
+2. Builds an **in-memory SQLite FTS5** virtual table (`porter` tokenizer) over
+   the chunks.
+3. Runs the intent as a **BM25-ranked** full-text query and returns up to
+   **3 matching snippets** (`MAX_SNIPPETS`).
+4. Appends a short list of searchable vocabulary terms so the agent can refine a
+   follow-up query.
+
+If FTS5 returns nothing, it falls back to a keyword scan of the chunks, and
+finally to plain truncation.
+
+### Safety guards
+
+Native tokenizers can choke on pathological input, so the compressor defends
+against it:
+
+- **Null-byte sanitization** — embedded `\0` bytes are stripped before insertion
+  to avoid tokenizer crashes.
+- **Per-chunk cap** — chunks are limited to **8 KB** (`MAX_CHUNK_BYTES`) to avoid
+  stressing the porter tokenizer on inputs with no word boundaries (base64 blobs,
+  minified JS, double-serialized JSON).
+- **Index ceiling** — outputs above **2 MB** (`MAX_INDEX_BYTES`) skip FTS5
+  entirely and fall back to truncation, since the native tokenizer can segfault on
+  very large unbroken inputs.
+- **Null/exotic results** — `null`/`undefined` results collapse to an empty
+  string; BigInt and circular values are coerced safely rather than producing
+  `"[object Object]"`.
+
+### Supplying intent
+
+The `execute_tool` proxy accepts an optional `intent` argument. From its schema
+([`tools/execute.ts`](../../src/mcp-router/tools/execute.ts)):
+
+> *Optional: describe what you are looking for in the output. For large results
+> (>10KB), only matching sections are returned instead of the full output.*
+
+So an agent calling a tool through the router can pass, e.g.,
+`intent: "the failing test name and stack frame"` and receive only the matching
+sections of an otherwise huge log.
+
+## Modules
+
+| Concern | Module |
+|---------|--------|
+| Stdio MCP server entrypoint | [`server.ts`](../../src/mcp-router/server.ts) |
+| Tool discovery (search across servers) | [`tools/discover.ts`](../../src/mcp-router/tools/discover.ts) |
+| Tool execution + output compression | [`tools/execute.ts`](../../src/mcp-router/tools/execute.ts) |
+| Output compression engine | [`output-compressor.ts`](../../src/mcp-router/output-compressor.ts) |
+| Per-session token-savings accounting | [`session-stats.ts`](../../src/mcp-router/session-stats.ts) |
+| Config parsing (`mcp.json`) | [`config/parser.ts`](../../src/mcp-router/config/parser.ts) |
+| Fuzzy tool search | [`search/fuzzy.ts`](../../src/mcp-router/search/fuzzy.ts) |
+
+## The `uap mcp-router` CLI
+
+Commands are defined in [`src/bin/cli.ts`](../../src/bin/cli.ts) and implemented
+in [`src/cli/mcp-router.ts`](../../src/cli/mcp-router.ts).
+
+### Start
+
+Run the router as a stdio MCP server (this is what a harness launches).
+
+```bash
+uap mcp-router start [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config <path>` | Path to an `mcp.json` config file |
+| `-v, --verbose` | Enable verbose logging |
+
+### Stats
+
+Show servers, tools, and token savings for the session.
+
+```bash
+uap mcp-router stats [-c <path>] [-v] [--json]
+```
+
+### Discover
+
+Find tools matching a query across all configured servers.
+
+```bash
+uap mcp-router discover -q "<query>" [options]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-q, --query <query>` | — | Search query (required) |
+| `-s, --server <server>` | — | Filter to a specific server |
+| `-l, --limit <limit>` | `10` | Max results |
+| `-c, --config <path>` | — | Path to `mcp.json` config file |
+| `-v, --verbose` | — | Enable verbose logging |
+| `--json` | — | Output as JSON |
+
+### List
+
+List the configured MCP servers.
+
+```bash
+uap mcp-router list [-c <path>] [--json]
+```
+
+## Enabling the router per harness
+
+The router replaces a harness's individual MCP servers with a single `router`
+entry that runs `uap mcp-router start`. The bundled installer wires this up for
+all supported harnesses:
+
+```bash
+uap mcp-setup [--force] [--verbose]
+```
+
+This command ([`src/cli/setup-mcp-router.ts`](../../src/cli/setup-mcp-router.ts))
+configures **Claude Code**, **Factory.AI**, **VSCode**, and **Cursor**. It writes
+a `router` server into each harness's MCP config:
+
+- **Claude Code** — `~/.claude/settings.json`
+- **Factory.AI** — `~/.factory/mcp.json`
+- **VSCode** — `~/.vscode/mcp.json`
+- **Cursor** — `~/.cursor/settings.json`
+
+The entry it installs looks like:
+
+```json
+{
+  "mcpServers": {
+    "router": {
+      "command": "npx",
+      "args": ["uap", "mcp-router", "start"],
+      "description": "Unified MCP Router - routes all tool calls"
+    }
+  }
+}
+```
+
+When a harness already has MCP servers configured, `mcp-setup` migrates them
+behind the router (preserving the originals in a backup field) — pass `--force` to
+skip the confirmation prompt. After setup it validates the install by running
+`uap mcp-router list`.
+
+## The savings
+
+For the common case where a tool returns a large, mostly-irrelevant payload and
+the agent supplies an intent, the router returns only the 3 best-matching
+snippets — **up to 98% fewer tokens** than the raw output. Small outputs (≤5 KB)
+pass through untouched, so there is no penalty for the common small-result case.
+Per-session savings are tracked in
+[`session-stats.ts`](../../src/mcp-router/session-stats.ts) and surfaced via
+`uap mcp-router stats`.
+
+See also the [Memory guide](./MEMORY.md) for reducing token spend on persistent
+context rather than tool output.

package/docs/guides/MEMORY.md

@@ -0,0 +1,235 @@
+# Memory System
+
+> UAP v1.40.0
+
+The Universal Agent Protocol gives agents a persistent, multi-tier memory so
+that learnings survive across sessions, compactions, and even harness switches.
+The system is implemented as 27 modules under [`src/memory/`](../../src/memory/)
+and is driven from the `uap memory` CLI.
+
+The design goal is **token efficiency**: instead of replaying entire transcripts
+into the context window, agents write small, high-signal memories and retrieve
+only the most relevant ones on demand via semantic search.
+
+## The four tiers
+
+Memory flows from a cheap, high-churn staging area down to a durable, searchable
+archive. Each tier has a distinct cost/permanence trade-off.
+
+| Tier | Name | Storage | Purpose | Module(s) |
+|------|------|---------|---------|-----------|
+| 0 | Daily log | SQLite | Staging area for raw writes; "log first, promote later" | [`daily-log.ts`](../../src/memory/daily-log.ts), [`short-term/sqlite.ts`](../../src/memory/short-term/sqlite.ts), [`short-term/schema.ts`](../../src/memory/short-term/schema.ts) |
+| 1 | Working cache | In-process / SQLite | Hot context with decay; predictive prefetch | [`speculative-cache.ts`](../../src/memory/speculative-cache.ts), [`predictive-memory.ts`](../../src/memory/predictive-memory.ts) |
+| 2 | Semantic | Qdrant vectors | Embedding-based recall over consolidated knowledge | [`serverless-qdrant.ts`](../../src/memory/serverless-qdrant.ts), [`embeddings.ts`](../../src/memory/embeddings.ts) |
+| 3 | Long-term archive | Pluggable backends | Durable, auditable store of promoted learnings | [`backends/base.ts`](../../src/memory/backends/base.ts), [`backends/factory.ts`](../../src/memory/backends/factory.ts), [`backends/github.ts`](../../src/memory/backends/github.ts), [`backends/qdrant-cloud.ts`](../../src/memory/backends/qdrant-cloud.ts) |
+
+### Tier 0 — Daily log
+
+Every observation an agent records lands first in the daily log, a SQLite-backed
+staging table (`daily_log`). This follows a "log first, promote later" pattern:
+writes are cheap and non-destructive, and a separate review step decides which
+entries are worth keeping. Each entry carries a `suggestedTier` of either
+`working` or `semantic` so promotion is guided rather than blind. See
+[`daily-log.ts`](../../src/memory/daily-log.ts).
+
+### Tier 1 — Working cache
+
+The working cache holds the hot context an agent is likely to need next. Entries
+**decay** over time so the cache stays small and relevant, and a predictive layer
+prefetches likely-needed memories. See
+[`speculative-cache.ts`](../../src/memory/speculative-cache.ts) and
+[`predictive-memory.ts`](../../src/memory/predictive-memory.ts).
+
+### Tier 2 — Semantic
+
+Consolidated knowledge is embedded and stored as vectors in Qdrant. Recall is by
+semantic similarity rather than exact match, so a query retrieves conceptually
+related memories even when the wording differs. See
+[`serverless-qdrant.ts`](../../src/memory/serverless-qdrant.ts).
+
+### Tier 3 — Long-term archive
+
+The durable archive is backend-pluggable. The bundled backends are selected via
+[`backends/factory.ts`](../../src/memory/backends/factory.ts):
+
+- **Qdrant Cloud** — managed vector store ([`backends/qdrant-cloud.ts`](../../src/memory/backends/qdrant-cloud.ts))
+- **GitHub** — version-controlled archive ([`backends/github.ts`](../../src/memory/backends/github.ts))
+- A common interface defined in [`backends/base.ts`](../../src/memory/backends/base.ts)
+
+## Semantic recall
+
+Tier 2/3 recall uses **real embeddings**, not placeholder hashes. The default
+provider runs a local `nomic-embed-text-v2-moe` model via `llama-server` (or
+Ollama) and produces **768-dimensional** vectors (Matryoshka — truncatable to
+256). Running embeddings locally means semantic recall incurs no per-query API
+cost. See [`embeddings.ts`](../../src/memory/embeddings.ts).
+
+Queries return matches ranked by cosine similarity, filtered by a configurable
+threshold (default `0.35`).
+
+## Write gates
+
+Not every observation deserves to be a memory. The write gate
+([`write-gate.ts`](../../src/memory/write-gate.ts)) scores incoming content and
+**rejects low-value writes** before they consume storage or pollute recall.
+Rejections include:
+
+- Empty content
+- Content too short to be a meaningful memory
+- Content matching a **noise pattern** (acknowledgements, transient requests)
+
+Content that records a **decision and its reasoning**, a durable **preference or
+convention**, or other high-signal information passes the gate. Rejected writes
+come back with a `rejectionReason` so the caller knows why.
+
+The gate can be bypassed deliberately with `--force` on `uap memory store`.
+
+## Correction propagation
+
+When a fact changes, you don't want stale copies lingering across tiers. The
+correction propagator ([`correction-propagator.ts`](../../src/memory/correction-propagator.ts))
+applies a correction **across all tiers** and marks the superseded entries with a
+date and reason, preserving an **audit trail** in a `superseded_entries` table
+rather than silently deleting. The result reports `tiersUpdated` and
+`supersededCount`.
+
+Trigger it from the CLI with `uap memory correct`.
+
+## Supporting modules
+
+Beyond the tiers, the system includes consolidation
+([`memory-consolidator.ts`](../../src/memory/memory-consolidator.ts)), a
+knowledge graph ([`knowledge-graph.ts`](../../src/memory/knowledge-graph.ts)),
+task classification ([`task-classifier.ts`](../../src/memory/task-classifier.ts)),
+dynamic retrieval ([`dynamic-retrieval.ts`](../../src/memory/dynamic-retrieval.ts)),
+semantic compression
+([`semantic-compression.ts`](../../src/memory/semantic-compression.ts)), and
+scheduled maintenance
+([`memory-maintenance.ts`](../../src/memory/memory-maintenance.ts)).
+
+## The `uap memory` CLI
+
+All commands are defined in [`src/bin/cli.ts`](../../src/bin/cli.ts) and
+implemented in [`src/cli/memory.ts`](../../src/cli/memory.ts).
+
+```bash
+uap memory status        # Show memory system status
+uap memory start         # Start memory services (Qdrant container)
+uap memory stop          # Stop memory services
+```
+
+### Query
+
+```bash
+uap memory query <search> [options]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-n, --limit <number>` | `10` | Max results |
+| `-k, --top-k <number>` | `10` | Alias for `--limit` |
+| `-t, --threshold <number>` | `0.35` | Minimum similarity score (0–1) |
+
+```bash
+uap memory query "qdrant connection retry" --limit 5 --threshold 0.5
+```
+
+### Store
+
+```bash
+uap memory store <content> [options]
+```
+
+Applies the write gate unless `--force` is passed.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-t, --tags <tags>` | — | Comma-separated tags |
+| `-i, --importance <number>` | `5` | Importance score (1–10) |
+| `-f, --force` | — | Bypass the write gate (store without quality check) |
+
+```bash
+uap memory store "Chose Qdrant over pgvector for HNSW recall speed" \
+  --tags architecture,memory --importance 8
+```
+
+### Prepopulate
+
+Seed memory from existing project knowledge.
+
+```bash
+uap memory prepopulate [options]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--docs` | — | Import from documentation only |
+| `--git` | — | Import from git history only |
+| `-n, --limit <number>` | `500` | Limit git commits to analyze |
+| `--since <date>` | — | Only analyze commits since date (e.g. `2024-01-01`) |
+| `-v, --verbose` | — | Show detailed output |
+
+### Promote
+
+Review daily-log (Tier 0) entries and promote significant ones into working or
+semantic memory.
+
+```bash
+uap memory promote
+```
+
+### Correct
+
+Find an existing memory and supersede it with a correction that propagates across
+all tiers.
+
+```bash
+uap memory correct <search> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-c, --correction <text>` | The corrected content |
+| `-r, --reason <reason>` | Reason for the correction |
+
+```bash
+uap memory correct "uses pgvector" \
+  --correction "uses Qdrant for semantic recall" \
+  --reason "migrated in v1.26"
+```
+
+### Maintain
+
+Run scheduled maintenance: decay, prune stale entries, archive old ones, and
+remove duplicates.
+
+```bash
+uap memory maintain [-v|--verbose]
+```
+
+## How agents use memory
+
+The recommended decision loop (see the project `CLAUDE.md`) wires memory into
+every task:
+
+1. **READ** recent context with `uap memory query`.
+2. **QUERY** long-term memory for related learnings (semantic search).
+3. **ACT** on the task.
+4. **RECORD** observations back to the daily log (`uap memory store`).
+5. **PROMOTE** significant learnings to long-term memory (`uap memory promote`).
+
+Corrections discovered along the way are pushed with `uap memory correct` so the
+fix cascades across tiers.
+
+## How it saves tokens
+
+- Agents retrieve a handful of **relevant** memories instead of replaying whole
+  transcripts into context.
+- The **write gate** keeps storage and recall results free of noise, so each
+  retrieved item carries signal.
+- **Decay** and **maintenance** keep the working set small.
+- **Local embeddings** make semantic recall free of per-query API cost.
+- **Correction propagation** prevents stale duplicates from inflating results.
+
+See also the [MCP Router guide](./MCP_ROUTER.md) for compressing tool *output*
+before it reaches the model.