@octocodeai/freellama-mcp-server 0.1.0 → 0.6.0

package/README.md

@@ -1,59 +1,57 @@
 # FreeLlama MCP server
 
-Exposes FreeLlama's local-LLM control plane, and Ollama's lifecycle, as
-[MCP](https://modelcontextprotocol.io) tools, built on the official
-[TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
-
-## Understand the eight tools
-
-- `doctor`, `models`, `run_task`, `run_task_batch` — thin wrappers over the native NAPI bindings into the
-  Rust core (`../rust-core/src/napi.rs`); no CLI subprocess, no reimplemented routing logic.
-  `run_task { preview: true }` is the free decision-only form (the former `route` tool).
-  Preview and execution are separate calls: preview accepts routing fields only and rejects task
-  payloads or runtime controls instead of silently ignoring them.
-  `models { view: "library" }` queries the public `ollama.com` library (the former `search_models` tool).
-- `session` — creates and releases a bounded, idle-expiring model-affinity handle for related
-  route/task calls. It does not store messages, prompt history, or Ollama's runner KV cache.
-- `ollama_manage`, `ollama_delete` — Ollama's HTTP API for lifecycle operations the routing layer
-  doesn't cover.
-- `delegate_research` — offloads a grounded code-research question to a local model and returns a
-  verdict computed from what the run did.
-
-Use the smallest tool that owns the operation:
+![A brown cartoon llama stands on a pastel cloud background.](assets/logo.jpg)
 
-```mermaid
-flowchart TD
-    Q{"What does the client need?"}
-    Q -->|"Diagnose the local runtime"| D["doctor"]
-    Q -->|"Inspect installed, resident, detailed, raw, or online models"| M["models"]
-    Q -->|"Choose or execute one task"| R["run_task"]
-    Q -->|"Fan out independent tasks"| B["run_task_batch"]
-    Q -->|"Keep/release related-task model affinity"| S["session"]
-    Q -->|"Pull or stop a model"| O["ollama_manage"]
-    Q -->|"Permanently remove a named model"| X["ollama_delete"]
-    Q -->|"Ground an answer in workspace files"| G["delegate_research"]
-```
+This package exposes FreeLlama's management layer as Model Context Protocol (MCP) tools.
+Agents offload bounded tasks to local Ollama models; FreeLlama handles model selection, resource
+admission, memory checks, and routing to configured CPU/GPU backends. Results include execution
+evidence for the calling agent to inspect.
 
-| Tool | Why it exists |
-|---|---|
-| `doctor` | Makes runtime, version, memory, and configuration drift visible before work starts. |
-| `models` | Separates installed, resident, detailed, raw, and public-library questions instead of guessing from model names. |
-| `run_task` | Applies the same deterministic routing, confidence, admission, and execution contract as the Rust control plane. |
-| `run_task_batch` | Executes only caller-declared independent tasks. Stable IDs, a bounded dispatcher, 3:2:1 fair priority classes, and per-item errors make fan-out inspectable rather than implicit. |
-| `session` | Lets an agent explicitly own the lifetime of a bounded affinity handle without misrepresenting it as conversation or KV storage. |
-| `ollama_manage` | Exposes additive lifecycle operations that FreeLlama routing intentionally does not perform. |
-| `ollama_delete` | Keeps irreversible deletion separate and explicit so a client can guard it. |
-| `delegate_research` | Gives a local model bounded read-only tools and returns citations plus an independently computed verification verdict. |
+The agent owns prompts, task dependencies, and answer verification. The operator configures
+Ollama and model lifecycle permissions; Ollama performs inference. See
+[architecture](https://github.com/bgauryy/FreeLlama/blob/main/docs/ARCHITECTURE.md) for the full ownership boundary.
+The server uses the official [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+
+## Understand the tools
+
+`doctor`, `models`, `run_task`, and `task_jobs` call the Rust core through native NAPI bindings
+(`packages/rust-core/src/napi.rs`), with no CLI subprocess and no routing decisions in TypeScript; the
+TypeScript layer validates request shapes and derives presentation fields (see
+[what the MCP layer computes](#what-the-mcp-layer-computes)). `run_task` has four modes: one task,
+`tasks[]` (independent batch), `preview: true` (decision only, no inference), and `warm: true`
+(load an exact installed model, no generation). Preview and execution are separate calls: preview
+accepts routing fields only and rejects task payloads or runtime controls instead of silently
+ignoring them. `ollama_manage` and `ollama_delete` call Ollama's HTTP API directly for lifecycle
+operations the routing layer does not perform.
+
+Use the smallest tool that owns the operation; the canonical per-tool table is [Tools](#tools).
 
 ## Follow the agent workflow
 
-The server sends this workflow to every MCP client in its initialization instructions:
+The task lifecycle uses the UUID returned as `job.id` by `run_task {defer:true}`. A job is one
+submitted task; pass that UUID as `jobId` for every subsequent operation.
+
+| Operation | MCP call |
+|---|---|
+| List models | `models {view:"installed"}` |
+| Submit a task and receive its ID | `run_task {prompt:"Explain this code", defer:true}` |
+| List tasks with their states | `task_jobs {action:"list"}` |
+| Get one task's state, result, or error | `task_jobs {action:"get", jobId:"<returned UUID>"}` |
+| Stop one task and retain its record | `task_jobs {action:"cancel", jobId:"<returned UUID>"}` |
+| Stop one task and remove its record | `task_jobs {action:"remove", jobId:"<returned UUID>"}` |
+
+Removal waits for local permits to be released before deleting the record. It returns the ID and
+terminal status; subsequent lookup returns `404`. It does not unload a shared Ollama model or
+prove that physical computation has stopped. Receipts are bounded and lost on server restart;
+see [retention and task states](https://github.com/bgauryy/FreeLlama/blob/main/docs/MONITORING.md#read-the-live-status).
+
+Follow this workflow. The server's initialization instructions carry a compressed form of the
+same contract (inventory first, preview semantics, evidence levels, ownership, and pull approval):
 
 1. Start with `models {view:"installed"}`, then `models {view:"resident"}`. This gives a routing
    agent the smallest current inventory first.
 2. Call `doctor` only for runtime or configuration diagnosis. It returns `summary` by default;
-   use `view:"scheduler"` for configured/snapshot scheduling evidence or `view:"full"` for the
-   complete diagnostic. If Ollama is missing or unreachable, ask the operator to install or start it.
+   use `view:"status"` for live queues and limits or `view:"full"` for the complete diagnostic. If Ollama is missing or unreachable, ask the operator to install or start it.
 3. Classify the task. Offload embeddings, OCR/vision, bulk transforms, and sufficiently large
    grounded lookups; retain small lookups and high-stakes judgment in the calling agent.
 4. Prefer a qualified installed model and preview consequential work.
@@ -89,7 +87,7 @@ Use this economical sequence:
 For a delegated agent, estimated usable input is `contextTokens - outputTokens - safetyMarginTokens`
 (the default margin is 256). The adapter pins the system instruction and question, preserves the
 newest observations, compacts older observations into breadcrumbs, and refuses a pinned overflow
-by default. `pinnedOverflow:"clip"` is a deliberate quality-risk override. Initial token counting
+by default. `FREELLAMA_AGENT_PINNED_OVERFLOW=clip` is a deliberate quality-risk override. Initial token counting
 is conservative; successful Ollama calls calibrate later estimates.
 
 Do not confuse operational evidence with answer quality. A receipt can prove admission, token
@@ -97,7 +95,41 @@ counts, placement, or unloading. It cannot prove research correctness, coding ju
 throughput, or fairness from one run. Check the returned confidence, policy evidence, and benchmark
 evidence before accepting a consequential answer.
 
-### Measure avoided external cost
+### Token economics
+
+Offloading keeps source material and intermediate tool output out of the calling agent's context;
+the local model still spends tokens, power, and time. Per-call rows below come from one machine
+(M4 Pro, 48 GB unified memory); `~` values are estimates.
+
+| Work | Source tokens | Returned tokens | Preserved |
+|---|---:|---:|---:|
+| 6 grounded code questions | 59,208 | 1,742 | **97.1%** |
+| 4 text embeddings (307 ms) | 17,600 | ~200 | **98.9%** |
+| 1 image, OCR, byte-exact | 1,970 | 37 | **98.1%** |
+
+A dated MCP-envelope audit (2026-09-03, `characters / 4` as a rough token estimate) measured the
+duplicate text copy FreeLlama does not emit beside `structuredContent`: `doctor {view:"summary"}`
+avoids ~3,064 chars, `doctor {view:"full"}` ~10,651, `models {view:"raw", limit:1}` ~404. These
+are **not billed-token savings** unless the host would otherwise feed both representations to a
+model. The tool schema itself is per-turn rent, bounded by the
+[protocol context-budget test](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/test/integration/protocol.test.ts);
+read documentation resources on demand and filter unneeded tools where the client supports it.
+
+| Cost side | Measured |
+|---|---|
+| Grounded question latency | **7–62 s** vs ~1 s for a frontier model that already holds the file |
+| Scaling | turn-dominated: `seconds ≈ 9.8 × tool_calls`, correlation 0.811 over 60 runs |
+| Break-even | past ~1k tokens of source the token maths wins; below that, read the file directly |
+| Judgment ceiling | ~67% accurate, in the same confident tone as the ~99% case |
+
+Ollama prefix-cache reuse works on this path (a warm 2,462-token prefix re-prefilled in ~281 ms
+versus ~18.6 s cold, and survived an interleaved conversation), so per-turn cost is new-token
+prefill plus generation. Context compaction rewrites old observations and invalidates the cache
+from that point; leave headroom (for example `OLLAMA_KV_CACHE_TYPE=q8_0`) so compaction stays rare.
+Session-scale projections depend on provider, caching, and pricing; measure the client's actual
+transcript before claiming a token or billing reduction.
+
+#### Avoided external cost
 
 Every successful `run_task`, batch item, and `delegate_research` result includes `telemetry.local`
 when Ollama reports input/output token counts. To add `telemetry.externalEquivalent`, configure one
@@ -115,13 +147,28 @@ excludes provider caching and reasoning-token differences, retries, local electr
 amortization; it is not a provider bill or net-profit calculation. Partial or invalid rate-card
 configuration stops the MCP server at startup instead of emitting a misleading estimate.
 
-### Route images and OCR
+### Route images
 
 Use `run_task` for supplied image bytes, not `delegate_research`. Preview
 `{task:"vision", requiredCapabilities:["vision"], preview:true}` before a consequential image
 task. Execute separately with a prompt and base64 `images` values without data-URI prefixes. The
-`images` field requires an explicitly trialed vision model; inspect the execution receipt for
-admission and observed placement.
+`images` field needs an explicit trialed vision `model`, or an operator `[policies.vision]` entry in
+the serve policy file; without either the core refuses rather than trusting a `vision` capability
+tag. Inspect the execution receipt for admission and observed placement.
+
+Use the prompt the model documents; dedicated OCR models expect their own task prompts.
+FreeLlama adds no stop sequence or other option because of which model was chosen.
+
+Some models repeat their answer until the output cap. Set `stopOnRepetition:true` to stream the
+task and stop once the output repeats itself; everything generated is kept, and the result
+carries `output_check: {stopped_early: true, stop_reason, unique_prefix_chars, ...}`. Without it, a
+length-capped answer that ends in a loop gets `output_check: {repetition_loop: true,
+unique_prefix_chars, period_chars}`. Either way the MCP answer text shows one copy and the
+untrimmed output stays in `structuredContent.response`.
+
+Routing learns from these loops, not from model names: a model that keeps looping on a task kind
+(at least two loops in at most twice as many runs, listed as `observed_loops` by `models`) ranks
+last for automatic selection of that task. An explicit `model` or an operator policy still wins.
 
 FreeLlama can prove that it routed and ran a request. It cannot infer OCR or visual-reasoning
 quality from a capability tag, a model name, or GPU placement. Quality depends on the exact
@@ -129,15 +176,14 @@ installed model build, prompt and decoding settings, context/output budget, and
 memory and accelerator performance. Validate representative held-out images on the target machine
 and supply policy/benchmark evidence before automatically accepting a quality-sensitive result.
 
-The caller owns task decomposition and concurrent submission. The operator owns endpoints, exact
-CPU assignments, runtime settings, and lifecycle approval. FreeLlama owns qualification, managed
-placement and admission. Ollama and the OS/driver own runner loading and physical CPU/GPU execution.
+Ownership of decomposition, CPU assignments, placement, and physical execution follows the
+[responsibility boundary](https://github.com/bgauryy/FreeLlama/blob/main/docs/ARCHITECTURE.md#responsibility-boundary).
 
 ## Follow the architecture
 
 ```mermaid
 flowchart TD
-    C["MCP client"] -->|"stdio JSON-RPC"| B["dist/index.js: eight tool registrations"]
+    C["MCP client"] -->|"stdio JSON-RPC"| B["dist/index.js: tool registrations"]
     B --> N["native/index.js and platform addon"]
     N -->|"doctor"| L["Rust diagnostics"]
     N -->|"models installed/resident; run_task"| S["freellama serve"]
@@ -153,108 +199,127 @@ flowchart TD
 `doctor`, the installed/resident model views, and `run_task` use the NAPI binding instead of a CLI
 subprocess. Direct lifecycle and no-serve model views use Ollama HTTP. `delegate_research` starts a
 bounded adapter against an allowlisted workspace; each adapter model turn re-enters managed
-`run_task` as `coding`, so it shares routing, admission, and placement evidence. Routing logic is
-not duplicated in TypeScript.
+`run_task` as `coding`, so it shares routing, admission, and placement evidence. The adapters are
+TypeScript in `src/research/`, compiled to `dist/research/{bash-agent,octocode-agent}.js`, and run as
+`node <file>` in their own process group with the server's Node.js; no Python is required.
 
-## Read packaged documentation through MCP
+### What the MCP layer computes
 
-The published MCP package includes every Markdown file from the repository `docs/` directory. The
-repository directory remains the source of truth; the package build copies it into `docs/` and
-creates `docs/INDEX.md`.
+Model selection, confidence floors, admission, and placement are decided only in the Rust core.
+The TypeScript server adds a small set of derived fields on top of core results:
 
-MCP clients can list resources and read `freellama://docs/index`, then fetch exactly one relevant
-guide such as `freellama://docs/PRODUCTION`, `freellama://docs/CLI`, or
-`freellama://docs/OLLAMA_SYSTEM_OPTIMIZATION`. Resources are deliberately lazy: do not load every
-guide into an agent context. The server fails on startup if the generated index is absent, and the
-release verifier checks that the packed documents match the root `docs/` set.
+- request-shape validation (preview-only fields, embedding versus chat payloads, scope pairs);
+- answer text, embedding summaries, and optional avoided-cost telemetry for `run_task`;
+- `models {view:"resident"}` placement labels: `gpu_percent` from `resident_vram / resident_size`,
+  a processor label (core-observed processor first, otherwise derived from that ratio), and
+  mismatch or partial-offload warnings;
+- library-tag `fitsInMemory` against a conservative host-memory budget and a trial candidate;
+- the `delegate_research` verification verdict from per-model evidence and tool-call facts.
 
-## Build
+## Read packaged documentation through MCP
 
-Build the native addon from the repository root and this package in place.
+The published MCP package includes the top-level Markdown guides from the repository `docs/`
+directory (developer notes under `docs/dev/` are not packaged). The repository directory remains the
+source of truth; the package build copies it into `docs/`.
 
-```bash
-# From the repository root (yarn workspaces — one install for every package)
-yarn install
-yarn build
-```
+MCP clients can list resources and read `freellama://docs/index` (the repository `docs/README.md`),
+then fetch exactly one relevant guide such as `freellama://docs/PRODUCTION` or
+`freellama://docs/CLI`. Resources are deliberately lazy: do not load every guide into an agent
+context. The server fails on startup if the index is absent.
 
-`yarn build` writes **one** MCP file, `packages/mcp/dist/index.js` (shebang, executable). During
-checkout development it loads `native/freellama.<triple>.node`. Published installs resolve the
-matching `@octocodeai/freellama-native-<target>` optional package instead, so the base MCP package remains
-portable. Research adapters are copied into `adapters/` for packed installs.
 
-Piecewise, if you are iterating on one layer:
+## Run
 
-```bash
-# 1. Native addon → packages/mcp/native/freellama.<triple>.node
-yarn build:native
+**From npm (recommended):**
 
-# 2. This server → dist/index.js via esbuild (then copies the research adapters into adapters/)
-yarn workspace @octocodeai/freellama-mcp-server build
+```bash
+npx @octocodeai/freellama-mcp-server
 ```
 
-`yarn start` needs `dist/index.js` and the compiled `.node` addon — `yarn build` from the repository
-root produces both in a checkout. `dist/index.js` loads `native/index.js`, which loads a local addon
-first and then a matching optional platform package. The `.node` binary is gitignored (a build
-artifact); `native/index.js` and `native/index.d.ts` are hand-written and checked in.
-
-## Run
+**From the repository root after building:**
 
 ```bash
-node dist/index.js
+node packages/mcp/dist/index.js
 ```
 
-The server speaks MCP over stdio — launch it from an MCP client (for example, Claude Desktop's
-`claude_desktop_config.json`), not interactively.
+The server speaks MCP over stdio — configure it in your MCP client, do not run it interactively.
 
-## Test
+**Claude Desktop (`claude_desktop_config.json`):**
 
-Vitest, in three tiers (all TypeScript, under `test/`):
-
-| Tier | Command (from this package) | Checks | Needs |
-|---|---|---|---|
-| `test/unit/` | `yarn test` (watch: `yarn test:watch`) | pure functions straight from `src/*.ts` — no build step, this is the TDD loop | nothing, ~0.5s |
-| `test/integration/` | `yarn test:integration` | the built server over the real MCP protocol: tool contract, structured content, guardrails; rebuilds `dist/` itself | live Ollama on :11434, ~5s |
-| `test/e2e/` | `yarn test:e2e` | every tool against the live system: real routing/execution, pull → delete round trip (net-zero), a real delegated research run | serve + Ollama + models, ~40s |
+```json
+{
+  "mcpServers": {
+    "freellama": {
+      "command": "npx",
+      "args": ["@octocodeai/freellama-mcp-server"]
+    }
+  }
+}
+```
 
-The same commands work from the repository root (`yarn test` there also runs the CLI package's tests).
-The integration/e2e tiers fail fast with a readable message when Ollama is down, and the lifecycle
-test refuses to delete a model already installed on the test system.
+**Cursor / other clients** — use the same `command`/`args` shape in their MCP server config.
 
 ## Tools
 
 | Tool | Needs `freellama serve`? | What it does |
 |---|---|---|
-| `doctor` | No | Runtime/configuration diagnostic. `summary` (default) returns endpoint, version, resident count, host/profile signals, and next step; `scheduler` adds configured/snapshot admission data; `config` returns categorized settings; `full` adds all non-duplicated diagnostics. The report distinguishes an observed same-user macOS process from configuration hints and never claims remote process visibility. |
-| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, real max context), paged `raw` (`GET /api/tags`), `library` (two-step ollama.com search: omit `model` for families, pass `model:"<family>"` for tags/`fitsInMemory`) |
-| `run_task` | Yes | **Routes or executes** a chat/generate/embed call. `preview: true` accepts routing fields only and returns a decision without generation. Execution omits preview and supplies the payload. Embedding results withhold raw vectors by default (`returnEmbeddings: true` to get them) |
-| `run_task_batch` | Yes | Executes only typed `{id, independent:true, task}` items. The nested `task` exposes the same task, routing, payload, and runtime controls as `run_task`; `maxParallelism` bounds fan-out. It is not a dependency graph scheduler. |
-| `ollama_manage` | No (direct to Ollama) | `action: "pull"` downloads a model; `action: "stop"` force-unloads it. Both additive and idempotent |
+| `doctor` | No (except `status`/`usage`) | Runtime/configuration diagnostic. Target another Ollama with `ollamaEndpoint` and serve with `serveEndpoint`. `summary` (default) returns endpoint, version, resident count, host/profile signals, and next step; `full` adds all non-duplicated diagnostics, including admission and categorized Ollama settings; `status` returns serve's live view (per-backend queues, current and adaptive limits, circuit breakers, loaded models, host memory, Ollama's effective settings, today's usage); `usage` returns task and token totals per day and model (`days`, default 7). The report distinguishes an observed same-user macOS process from configuration hints and never claims remote process visibility. |
+| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, use explanations, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, maximum context), paged `raw` (`GET /api/tags`), `library` (two-step ollama.com search: omit `model` for families, pass `model:"<family>"` for all tags/`fitsInMemory`). `includeLibrary:true` enriches installed/detail views with sourced public guidance; `includeReadme:true` returns bounded README text in library step 2 or enriched detail. |
+| `run_task` | Yes | **Routes or executes** a chat/generate/embed call. `preview: true` accepts routing fields only and returns a decision without generation. Execution omits preview and supplies the payload. Embedding results withhold raw vectors by default (`returnEmbeddings: true` to get them). `tasks: [{id, independent:true, task}]` (max 64, `maxParallelism` bounds fan-out) runs a batch whose nested `task` takes the same fields; it is not a dependency scheduler. `warm: true` warms an exact installed `model` through managed admission with residency/profile controls and optional `defer:true`. |
+| `scope` | Yes | Creates, inspects, forks, or deletes process-local message history; history inclusion requires `includeMessages:true`. |
+| `session` | Yes | Creates, deletes, or kills model affinity without storing messages or KV; `kill` cancels the session's in-flight work. |
+| `task_jobs` | Yes | Inspects, cancels, or removes a deferred task or warming operation. |
+| `ollama_manage` | No (direct to Ollama) | `action: "pull"` downloads a model (additive); `action: "stop"` force-unloads it. Both are idempotent |
 | `ollama_delete` | No (direct to Ollama) | **Destructive**: permanently removes a model. Call only on an explicit human instruction naming the exact model |
 | `delegate_research` | Yes (and spawns the adapter) | Answers a grounded question from files under `workspacePath`; managed coding turns return placement receipts, citations, and an independent verification verdict |
 
+### Inspect capabilities and intended uses
+
+Use `models {view:"installed", includeLibrary:true}` to enrich each installed model, or
+`models {view:"detail", model:"gemma3:1b", includeLibrary:true, includeReadme:true}` for one model.
+Website access is optional for installed/detail views. Public guidance requires a matching exact tag
+and digest prefix; local capabilities remain authoritative and benchmark/policy evidence stays separate.
+Family claims have source excerpts and fetch dates, and lookup failures retain local inventory.
+Search reports `cloudAvailable` (a cloud variant exists), not whether a family is cloud-only; inspect
+exact tags to establish local availability.
+See [Model metadata](https://github.com/bgauryy/FreeLlama/blob/main/docs/MODEL_SELECTION.md#model-metadata) for response fields, lookup states, cache bounds,
+custom models, and variant limitations.
+
 ### Preserve Ollama request controls
 
-All eight tools declare an MCP object `outputSchema`. Schemas type the stable fields FreeLlama owns
+The tools declare an MCP object `outputSchema`. Schemas type the stable fields FreeLlama owns
 (such as route decision, page, answer, and session identifiers) while leaving Ollama-owned nested
-payloads forward-compatible. `structuredContent` is canonical; normal text is a concise cue. For
-the narrow `delegate_research` legacy case, set `legacyText:true` to receive serialized JSON text.
+payloads forward-compatible. `structuredContent` is canonical; normal text is a concise cue
+(`run_task` and `delegate_research` return the answer text).
 
 Use `models {view:"raw", limit:20}` and continue with its opaque `page.next_cursor`; a cursor
 refuses continuation if the live model list changed. Library tag responses use the same paging
-shape. Do not request `doctor {view:"full"}` in an agent loop: use `summary`, `scheduler`, or
-`config` for the smallest diagnostic that answers the question.
+shape. Do not request `doctor {view:"full"}` in an agent loop: use `summary`, `status`, or `usage` for
+the smallest diagnostic that answers the question.
+
+### Preview and execution
+
+For ordinary chat, `run_task {prompt:"Hello"}` is enough once the server and an eligible model
+are available. `task` defaults to `completion`, including inside batch items. Task profiles are
+optional routing presets, not restrictions on what you can ask the model.
+
+Default `balanced` routing prefers policy-qualified candidates when available. Without an eligible
+policy candidate, it falls back to capability/context-compatible models and reports low confidence,
+`quality_evidence:"none"`, and `balanced_without_quality_policy`. Set `minConfidence:"medium"`
+to require evidence, or `objective:"quality"` to require policy-based selection unless you pin a model.
+Memory admission, authentication, and capability requirements apply in every mode.
 
 `run_task` has two deliberately exclusive request shapes:
 
 - Preview: set `preview: true`; pass routing fields such as `task`, `objective`, `model`,
   `contextTokens`, `requiredCapabilities`, and placement/confidence gates. To preview tool use,
   pass `requiredCapabilities: ["tools"]` rather than function definitions.
-- Execution: omit `preview` (or set it to `false`) and pass `prompt`/`messages` for generative
+- Execution: omit `preview` (or set it to `false`) and pass `prompt`, `systemPrompt`, or `messages` for generative
   tasks or `input` for embeddings, plus any applicable Ollama runtime controls.
 
-Preview rejects `prompt`, `messages`, `input`, `images`, `tools`, `keepAlive`, `format`, `think`,
-`options`, `logprobs`, `topLogprobs`, and `returnEmbeddings`. This prevents a client from attaching
+Preview rejects `prompt`, `systemPrompt`, `messages`, `input`, `images`, `tools`, `keepAlive`, `format`, `think`,
+`options`, `logprobs`, `topLogprobs`, `returnEmbeddings`, `priority`, `maxWaitSeconds`, `timeoutSeconds`, and
+`defer`, `scopeId`, and `scopeRevision`. This prevents a client from attaching
 work to a decision-only call and mistakenly assuming it ran.
 
 `run_task.messages` preserves Ollama message fields beyond `role` and `content`, including images,
@@ -263,11 +328,65 @@ thinking, tool calls, and tool names. Managed requests also accept `format`, `th
 keys are rejected inside `options`. The raw proxy remains available when a caller needs an Ollama
 endpoint or feature that the managed MCP tool does not expose, including streaming.
 
+Managed execution waits for a slot and safe host capacity within the server's waiting budget
+(120 seconds by default). Set `maxWaitSeconds` on `run_task` or each batch task to request a
+shorter budget; the server caps it at its configured limit. Resource waiters remain counted in
+the bounded queue after returning their execution slots. They resume when capacity becomes
+available, and session cancellation removes pending work. A full queue or an expired deadline
+returns a capacity error with retry guidance.
+
+Set `defer:true` on `run_task` to return a job ID immediately. Use `task_jobs {action:"list"}` for
+metadata, `{action:"get", jobId}` for a retained result, and `{action:"cancel", jobId}` to cancel
+that task and wait for local permits to be released. `get` summarizes embedding vectors by default;
+set `returnEmbeddings:true` to include them. Cancellation does not unload a shared model or confirm
+physical runner shutdown. Jobs expire on restart; see [CLI controls](https://github.com/bgauryy/FreeLlama/blob/main/docs/CLI.md#execute-tasks)
+for input, result, registry, and retention limits. Batch items cannot defer.
+
+Set `timeoutSeconds` on a task or batch item for a total deadline covering discovery, queueing,
+loading, and inference. The server caps it at its task timeout. The admission wait budget remains
+separate; a queue refusal can happen before the total deadline. `priority` selects a fair scheduling
+class without bypassing resource checks.
+
+You own the task instructions. Pass system prompts as `messages` entries with `role:"system"`,
+or use `systemPrompt` to prepend one caller-supplied system message. FreeLlama preserves existing
+messages and adds no task instructions of its own. A plain `prompt` becomes one user message,
+and a supplied `messages` array takes precedence over `prompt`. This also applies to
+`task:"code_review"` (an alias for `coding`) and `run_task {tasks}` batches: no review wrapper, mandatory
+JSON review format, or review-specific output-token minimum is added.
+
+The separate `delegate_research` adapter retains internal protocol prompts for its own bounded job. Those prompts are not injected into `run_task`
+conversations. Ollama can still apply the selected model's own template or Modelfile defaults.
+
 `model_type` is a display-oriented value derived from Ollama's additive capabilities:
 `generative`, `multimodal`, `embedding_only`, or `unknown`. Routing continues to use the original
 capability set, not this summary label. Unknown future Ollama capabilities are omitted from the
 typed routing set instead of being treated as a known capability.
 
+### Call the control API directly
+
+Scripts that bypass MCP post the same fields in snake_case to `POST /_freellama/v1/tasks`:
+`task`, `objective`, `model`, `session_id`, `required_capabilities`, `prompt` or `messages`,
+`images`, `priority`, `keep_alive`, `max_wait_seconds`, `timeout_seconds`, `stop_on_repetition`,
+and `request_options: {options, format, think, logprobs, top_logprobs}`. A batch is
+`{tasks: [{id, independent: true, task: {...}}], max_parallelism}`; sessions are
+`POST /_freellama/v1/sessions` with `{}`. `model` accepts a bare name (`name` resolves to
+`name:latest`, or the one installed tag of that family); an ambiguous or unknown name is refused
+with the installed candidates. See [Request shapes](https://github.com/bgauryy/FreeLlama/blob/main/docs/ARCHITECTURE.md#request-shapes)
+for a full body and the receipt fields.
+
+### Retain history and warm models
+
+Use `scope {action:"create",messages}` to retain a caller-owned prefix. Pass its returned ID and
+revision as `scopeId` and `scopeRevision` with only the new input to `run_task`; successful execution
+returns the next scope revision. Fork a snapshot before parallel branches. `sessionId` continues to
+mean model affinity only.
+
+Use `run_task {warm:true,model,contextTokens,keepAlive?}` for a matching runner profile. It accepts no task
+payload and does not pull a model. Add `defer:true` to inspect its progress through `task_jobs`.
+Explicit `keepAlive` wins over finite adaptive retention. See the canonical
+[Scope history and model warming reference](https://github.com/bgauryy/FreeLlama/blob/main/docs/SCOPES_AND_WARMING.md) for schemas, limits,
+concurrency, privacy, and cache boundaries.
+
 ### Use CPU assignments through MCP
 
 `run_task` delegates to `freellama serve`, so it honors the server's `--cpu-upstream` and
@@ -277,17 +396,34 @@ managed tasks execute on the primary GPU-capable process.
 Set `executionPreference` on `run_task` to `auto` (default), `prefer_cpu`, or `prefer_gpu`. This is a
 guarded hint: only exact operator-assigned CPU models are eligible, explicit model/session pins win,
 and `preview: true` returns `execution.preference_satisfied`, placement, upstream, admission, and a
-reason without generating. Automatic feedback normalizes work by tokens, waits for three successful
-warm, physically verified samples per task on both backends, requires a 10% advantage, and never
-steers the `quality` objective. `minPlacementEvidence:"observed"` fails closed unless resident
+reason without generating. Automatic feedback normalizes work by tokens and requires three
+comparable warm serial samples on both backends with a 10% advantage. It matches model digest,
+explicit observed context, effective controls, endpoint-attributed process settings, and managed
+admission class. Unknown identity, parallel intervals, and decision-only payload-free previews
+use capacity and policy signals. Stored legacy totals do not qualify speed hints. Feedback does
+not steer the `quality` objective. See [automatic feedback](https://github.com/bgauryy/FreeLlama/blob/main/docs/CPU_GPU_ROUTING.md#understand-automatic-feedback).
+`minPlacementEvidence:"observed"` fails closed unless resident
 `/api/ps` evidence matches the configured processor; warm cold models once with `"configured"`.
 `keepAlive:"0"` uses an observe-then-unload transaction: FreeLlama retains the runner long enough
 to inspect `/api/ps`, accepts feedback only for verified placement, requests an explicit unload,
 then reports the unload verification in `execution.lifecycle`.
 
+Preview `execution.agent_plan` separates `queue_readiness`, `resource_readiness`, and combined
+`dispatch_readiness`. Inspect `execution.resource_assessment` for required bytes and missing telemetry;
+the preview shares execution's footprint estimate but never reserves memory. Low available RAM alone
+never refuses work: previews report `runnable_low_memory_estimate`, and execution dispatches with
+`resource_admission.status: "admitted_low_memory_estimate"`. Local inference requires
+RAM telemetry by default; configure an explicit alternative on `serve`, not in a model prompt.
+Resource errors retain a human-readable `error` plus machine-readable `code` and `resource_admission`
+fields in the HTTP response. MCP preserves JSON refusals in both error text and `structuredContent`,
+including queue-full codes, `retry_after_seconds`, resource assessments, and unload receipts.
+Agents can use those fields to back off or explain a capacity hold without parsing human prose.
+
 `models {view: "resident"}` uses the managed catalog, so it includes resident models from both
 Ollama processes and labels explicitly assigned CPU models instead of querying only the primary
-server.
+server. The per-model `placement` object is derived in the MCP layer from the catalog's
+`resident_size`/`resident_vram` bytes and the core's placement observation; it is a display summary,
+not new placement evidence.
 
 Before relying on that placement, query `/_freellama/v1/health` and require
 `contracts.placement_observation:"ollama_api_ps_after_execution"` and
@@ -298,129 +434,11 @@ The direct Ollama tools do not infer that assignment. `ollama_manage`, `ollama_d
 no-serve model views target their explicit `ollamaEndpoint` or `FREELLAMA_OLLAMA_ENDPOINT`, which
 defaults to the primary Ollama server. Point them at the CPU endpoint only when you intend to
 inspect or modify that separate server. Read
-[CPU and GPU model routing](docs/CPU_GPU_ROUTING.md) for the complete contract.
-
-## Configuration
-
-Every default is overridable through an environment variable — set them in the MCP client's
-server-launch config (for example `.mcp.json`'s `env` block) or the launching shell.
-
-| Variable | Default | Affects |
-|---|---|---|
-| `FREELLAMA_OLLAMA_ENDPOINT` | `http://127.0.0.1:11434` | `doctor` and all `ollama_*` tools' default Ollama endpoint |
-| `FREELLAMA_SERVE_ENDPOINT` | `http://127.0.0.1:11435` | Default `endpoint` for serve-backed tools and `delegate_research` |
-| `FREELLAMA_MCP_DEFAULT_MODEL` | `qwen3.8:27b-mlx` | `delegate_research`'s default `model` |
-| `FREELLAMA_MCP_DEFAULT_ADAPTER` | `bash` | `delegate_research`'s adapter (`octocode` to switch) |
-| `FREELLAMA_MCP_MAX_TURNS` | `8` | Max agent turns for `delegate_research` |
-| `FREELLAMA_MCP_DELEGATE_TIMEOUT_SECONDS` | `180` | Whole-subprocess timeout for `delegate_research` |
-| `FREELLAMA_MCP_PULL_TIMEOUT_SECONDS` | `1200` | Default `ollama_manage` `"pull"` timeout |
-| `FREELLAMA_MCP_FETCH_TIMEOUT_SECONDS` | `30` | Timeout for other direct Ollama HTTP calls |
-| `FREELLAMA_MCP_ALLOWED_ROOTS` | checkout: this repository; published: must be set | Platform-separated allowlist of directories `delegate_research` may read (`:` on macOS/Linux, `;` on Windows) |
-| `FREELLAMA_MCP_MODEL_EVIDENCE` | checkout: `benchmark/evidence/model-evidence.json`; published: unset | Path to per-model research grades (see "Runtime evidence") |
-| `FREELLAMA_EXTERNAL_COST_MODEL` | unset | External-model label in estimated avoided-cost telemetry; set all three cost variables or none |
-| `FREELLAMA_EXTERNAL_COST_INPUT_USD_PER_M` | unset | External input USD per million tokens |
-| `FREELLAMA_EXTERNAL_COST_OUTPUT_USD_PER_M` | unset | External output USD per million tokens |
-| `FREELLAMA_CONTROL_TIMEOUT_SECONDS` | `30` | Decision-only serve calls; read by `../rust-core/src/napi.rs` |
-| `FREELLAMA_TASK_TIMEOUT_SECONDS` | `900` | Generation calls; read by `../rust-core/src/napi.rs` |
-| `FREELLAMA_AUTH_TOKEN_FILE` | unset | Bearer-token file used by the native client and research adapters for all serve routes |
-| `FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR` | platform data directory | Prompt-free, model-specific token-estimator calibration shared across adapter processes |
-
-Research-adapter settings are deployment defaults. The optional `delegate_research.agent` object
-exposes the same values per call using camelCase; explicit per-call fields win.
-
-| Variable | Default | Affects |
-|---|---:|---|
-| `FREELLAMA_AGENT_NUM_CTX` | `8192` | Ollama context window |
-| `FREELLAMA_AGENT_EXECUTION_PREFERENCE` | `auto` | Managed coding-agent backend hint |
-| `FREELLAMA_AGENT_MIN_PLACEMENT_EVIDENCE` | `configured` | Set `observed` to fail closed on cold/mismatched placement |
-| `FREELLAMA_AGENT_NUM_PREDICT` | `512` | Reserved output budget |
-| `FREELLAMA_AGENT_TEMPERATURE` / `FREELLAMA_AGENT_SEED` | `0` / `42` | Repeatable decoding |
-| `FREELLAMA_AGENT_THINK` / `FREELLAMA_AGENT_KEEP_ALIVE` | `false` / `5m` | Ollama reasoning and residency |
-| `FREELLAMA_AGENT_REQUEST_TIMEOUT_SECONDS` | `600` | Each Ollama chat attempt |
-| `FREELLAMA_AGENT_TOOL_TIMEOUT_SECONDS` | Bash `30`, Octocode `45` | Each local tool call |
-| `FREELLAMA_AGENT_RETRY_ATTEMPTS` / `FREELLAMA_AGENT_RETRY_BACKOFF_SECONDS` | `2` / `5` | Conversation-level retry |
-| `FREELLAMA_AGENT_MAX_PARSE_REPAIRS` / `FREELLAMA_AGENT_PARSE_REPAIR_ECHO_CHARS` | `2` / `500` | Invalid JSON correction limit and retained reply text |
-| `FREELLAMA_AGENT_CHARS_PER_TOKEN` | `4` | First-call token estimate; later calibrated from Ollama |
-| `FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS` | `256` | Input headroom beyond `num_predict` |
-| `FREELLAMA_AGENT_IMAGE_TOKEN_ESTIMATE` | `1024` | Bounded charge per image |
-| `FREELLAMA_AGENT_KEEP_RECENT` | `2` | Recent observations preserved verbatim |
-| `FREELLAMA_AGENT_COMPACT_PREVIEW_CHARS` | `180` | Old-observation breadcrumb size |
-| `FREELLAMA_AGENT_COMPACT_RETAIN_RATIO` | `0.8` | Current payload retained per emergency pass |
-| `FREELLAMA_AGENT_CLIP_HEAD_RATIO` | `0.667` | Head share when an emergency clip preserves both ends |
-| `FREELLAMA_AGENT_OBSERVATION_PAGE_CHARS` | `3000` | Lossless observation page target |
-| `FREELLAMA_AGENT_PINNED_OVERFLOW` | `error` | Preserve system/task bytes; `clip` is explicit opt-in |
-
-Invalid values fail before an Ollama request. Each successful result returns
-`contextManagement` with the resolved policy, calibration source/scale, estimated input budget,
-and compaction count. Ollama has no stable preflight tokenizer endpoint, so “exact before the first
-call” is not claimed. Model-specific calibration persists after successful calls, so later
-processes start conservatively from prior `prompt_eval_count` evidence without sharing estimates
-between model templates.
-
-**Security:** `delegate_research` grants a local model read access to `workspacePath`. The path is
-confined to `FREELLAMA_MCP_ALLOWED_ROOTS` (default: this repository in a checkout; unset in a published
-install until you set it), resolved through symlinks so a link inside an allowed root can't escape
-it. The default `bash` adapter also rejects home-directory paths, `..`, and absolute paths outside
-that workspace. Production deployments should generate a permission-restricted token with
-`freellama auth-token`, start `serve` with `--auth-token-file`, and set
-`FREELLAMA_AUTH_TOKEN_FILE` for MCP. Authentication covers managed and raw passthrough routes; use
-an external TLS and authorization layer for untrusted or multi-tenant networks.
-
-### Runtime evidence
-
-**No measurements are compiled in.** In a repository checkout, per-model research grades load from
-`benchmark/evidence/model-evidence.json`. A published package does not include that repository
-file, so its evidence table is empty unless you set `FREELLAMA_MCP_MODEL_EVIDENCE`. An unmeasured
-model yields a `verify` verdict. Tool descriptions state the rules; measurement details live in
-`skills/freellama/references/` and `.octocode/evals/`.
-
-## Platform support
-
-The native addon is named by target triple (`freellama.<platform>-<arch>[-<abi>].node`). The base
-package has eight npm optional dependencies, one each for macOS arm64/x64, Linux arm64/x64 with
-glibc or musl, and Windows arm64/x64 with MSVC. `native/index.js` tries the checkout artifact first,
-then the host's optional package. A release is supported only when all eight artifact packages pass
-the publish verifier; an installation made with `--omit=optional` cannot load the addon. `engines`
-requires Node >= 20.
-
-Machine discovery distinguishes total host memory (`memory_bytes`) from known unified memory
-(`unified_memory_bytes`). Library-tag `fitsInMemory` is a conservative host-memory preflight and
-includes `fitScope: "host_memory_budget_only"`; inspect `/api/ps` for actual accelerator placement.
-
-Start the serve-backed tools' dependency from the repository root:
-
-```bash
-cargo run --release -- serve --recommendation-catalog recommendations.example.toml
-```
-
-See `skills/freellama/references/proxy-vs-serve.md` for the `proxy` vs `serve` distinction (only
-`serve` has the `/_freellama/v1/*` routes these tools call).
-
-## Publish
+[CPU and GPU model routing](https://github.com/bgauryy/FreeLlama/blob/main/docs/CPU_GPU_ROUTING.md) for the complete contract.
 
-`packages/mcp/` is the portable JavaScript package. Its `package.json` lists the platform packages
-as exact-version optional dependencies; it intentionally does not embed a `.node` binary. Publish
-the eight `packages/native/*` packages first, then publish `@octocodeai/freellama` and `@octocodeai/freellama-mcp-server`
-at the same version. `yarn release:verify:publish` refuses a release if any platform package has a
-missing, empty, or unpacked executable/addon pair.
-
-```bash
-cd packages/mcp
-npm pack --dry-run   # confirm exactly what a publish would ship
-```
+## More
 
-Version 0.1.0 is not published to a registry. Treat `npm publish` as a real, irreversible public
-action, and confirm with the repository owner first.
-
-## Why native bindings
-
-- **No reimplementation.** `run_task`, `route`/`preview`, and the installed-model list are HTTP
-  calls into a running `freellama serve`, matching `../cli/src/main.rs`. `doctor` talks to Ollama
-  and the host's portable machine-discovery layer directly. `ollama_manage` / `ollama_delete` hit Ollama's HTTP API. `delegate_research`
-  is a subprocess. Routing logic still lives in exactly one place — the Rust core.
-- **One connection pool.** `../rust-core/src/napi.rs` holds a single `reqwest::Client` in a
-  `OnceLock` and clones the handle per request, matching the server side.
-- **`unsafe_code` stays isolated.** The crate is `deny(unsafe_code)` except `napi.rs`, which
-  carries an explicit `#[allow(unsafe_code)]` for napi-derive's FFI glue.
-- **The napi build is off by default** (`cargo build` never touches it); the addon is built with
-  `napi build --features napi` from the repo root.
+- [Configuration](CONFIGURATION.md): environment variables, research-adapter settings, security,
+  and runtime evidence.
+- [Developing](DEVELOPING.md): build, test tiers, platform packages, publishing, and why the server
+  uses native bindings.