@octocodeai/freellama-mcp-server 0.10.0 → 0.12.0

package/CONFIGURATION.md

@@ -11,6 +11,7 @@ server-launch config (for example `.mcp.json`'s `env` block) or the launching sh
 |---|---|---|
 | `FREELLAMA_OLLAMA_ENDPOINT` | `http://127.0.0.1:11434` | Default Ollama endpoint for `doctor`, the `models` detail/raw/library views, all `ollama_*` tools, and the autostarted serve's `--upstream` |
 | `FREELLAMA_SERVE_ENDPOINT` | `http://127.0.0.1:11435` | Default `endpoint` for serve-backed tools and `delegate_research` |
+| `FREELLAMA_MCP_RECEIPT` | `text` | `structured` keeps `run_task` and `task_jobs` receipts inline as `structuredContent` (see [Where an answer goes](#where-an-answer-goes)) |
 | `FREELLAMA_MCP_DEFAULT_MODEL` | unset (routes to an installed coding model) | `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` |
@@ -27,12 +28,16 @@ server-launch config (for example `.mcp.json`'s `env` block) or the launching sh
 | `FREELLAMA_TASK_TIMEOUT_SECONDS` | `900` | Generation calls; read by the native client (`packages/rust-core/src/serve_client.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 |
-| `FREELLAMA_MCP_AUTOSTART_SERVE` | `1` | When the default loopback serve endpoint does not answer, start `freellama serve` as a child of the MCP server (stopped with it): once in the background at launch, so other local clients find it, and again on a tool call if it is still down. `0` disables |
+| `FREELLAMA_MCP_AUTOSTART_SERVE` | `1` | When the default loopback serve endpoint does not answer, start `freellama serve` as a child of the MCP server (stopped with it): once in the background at launch, so other local clients find it, and again on a tool call if it is still down. Under the agent commands (`freellama run`, `chat`…) it starts detached instead, logging to `$FREELLAMA_HOME/serve.log` (default `~/.octocode/freellama/serve.log`), and keeps running for later calls. `0` disables |
+| `FREELLAMA_WORKFLOWS_DIR` | `$FREELLAMA_HOME/workflows` | Directory of your own workflow files (`NAME.md`), read when the MCP server or an agent command starts. A file named like a built-in replaces it; an invalid one is skipped and named by `freellama workflows` and `doctor`. Format: [your own workflows](../../docs/PROMPTS.md#your-own-workflows) |
+| `FREELLAMA_EMBED_INDEX` | `1` | `0` turns off the persistent embedding index that lets a repeated `nearest` search over files (find-code, duplicates) embed only new or changed chunks. Vectors live in `$FREELLAMA_HOME/embedding-index/`, one file per model, digest and dimensions. |
+| `FREELLAMA_OLLAMA_CLI` | `ollama` | Path of the `ollama` binary that `freellama chat` runs |
 | `FREELLAMA_SERVE_BINARY` | checkout `target/release`/`debug`, then the platform package | Binary used for serve autostart |
 | `FREELLAMA_AGENT_OS_SANDBOX` | `auto` | Bash adapter OS confinement: `bwrap` on Linux, `sandbox-exec` on macOS, when present. `off` keeps only the restricted shell |
 | `FREELLAMA_AGENT_OCTOCODE_PACKAGE` | `octocode@19.1.0` | Pinned npm spec the Octocode adapter runs through `npx` |
-| `FREELLAMA_MCP_ALLOW_CODER` | unset (off) | `1` enables `delegate_research` `adapter:"coder"`, which edits files and runs the caller's `agent.commands` in an isolated copy of the workspace (see [the coder adapter](README.md#the-coder-adapter)) |
+| `FREELLAMA_MCP_ALLOW_CODER` | unset (off) | `1` enables `delegate_research` `adapter:"coder"`, which edits files and runs the caller's `agent.commands` in an isolated copy of the workspace and returns a patch for the caller to review and `git apply` (see [`src/research/coder-agent.ts`](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/src/research/coder-agent.ts)) |
 | `FREELLAMA_CODER_RUN_TIMEOUT_SECONDS` | `300` (at most `1800`) | Timeout of one coder `run`; the whole call is still bounded by `agent.timeoutSeconds` (coder default at least 600 s) |
+| `FREELLAMA_CODER_MAX_OUTPUT_BYTES` | `16777216` (16 MiB; at most 256 MiB) | Retained raw stdout/stderr cap per coder command. Overflow or a log-write error terminates the command and reports incomplete output. Model previews remain bounded separately; retained files have no aggregate cross-session quota |
 | `FREELLAMA_CODER_MAX_COPY_BYTES` | `209715200` (200 MB) | Size cap of a coder copy of a workspace that is not a git repository (`node_modules`, `target`, `dist` and `.git` excluded) |
 | `FREELLAMA_CODER_WRITABLE` | unset | Platform-separated extra directories the coder's allowed commands may write, such as `~/.cargo` for `cargo test`; an entry that holds or lies inside the workspace is refused |
 | `FREELLAMA_CODER_UNSANDBOXED_RUN` | unset | `1` lets the coder `run` without an OS sandbox (`sandbox-exec` or `bwrap`); without one, `run` is refused |
@@ -44,6 +49,8 @@ Serve-side placement settings (read by `freellama serve`, not the MCP process):
 | `FREELLAMA_EVICT_IDLE_MODELS` | on | Unload idle, unpinned models using reuse and load costs when a cold load needs room. `0` turns eviction off |
 | `FREELLAMA_CPU_NUM_THREAD` | half the logical cores (not set on macOS) | `num_thread` for CPU-placed tasks only; GPU tasks leave it to Ollama |
 | `FREELLAMA_MAX_QUEUE_WAIT_SECONDS` | `120` | How long a managed task queues for a slot or memory |
+| `FREELLAMA_MAX_REQUEST_BYTES` | `67108864` (64 MiB) | Managed request/response byte cap; Ollama embedding, decision, error and NDJSON response bytes share it. Buffered terminal and rewritten gateway responses use the same per-response bound before UTF-8 decoding, including SSE/JSON/error bodies; fetch may already have decompressed them. Overflow fails without replay (502 before gateway headers, stream failure afterward, CLI exit 1); raw real-tag passthrough remains pull-driven |
+| `FREELLAMA_DURABLE_JOBS` | off | `true`/`1` enables durable deferred receipts and idempotency with a file-backed store; prompts are not persisted or replayed. See [durable deferred jobs](../../docs/DEFERRED_JOBS.md) |
 | `OLLAMA_NUM_PARALLEL`, `OLLAMA_KV_CACHE_TYPE`, `OLLAMA_FLASH_ATTENTION` | Ollama's | Read as hints for the memory estimate: parallel slots multiply the KV cache, and `q8_0`/`q4_0` shrink it only with flash attention. Set them for serve the same way as for Ollama |
 
 Research-adapter settings are deployment defaults. The optional `delegate_research.agent` object
@@ -107,8 +114,80 @@ managed admission; it does not create Ollama
 slots or relax memory guards. Existing queued work keeps its captured cost. See
 [monitoring controls](https://github.com/bgauryy/FreeLlama/blob/main/docs/MONITORING.md#adaptive-concurrency).
 
-**No measurements are compiled in.** In a repository checkout, per-model research grades load from
+Research-adapter grades load at runtime. In a repository checkout, per-model research grades load from
 `packages/mcp/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, and an unreadable evidence file is reported on stderr and treated
 as empty. Tool descriptions state the rules.
+
+Job/workflow model selection first consumes the Rust router's machine-local throughput evidence,
+then falls back to the portable installed-model catalog when that evidence is unavailable or
+insufficient. Capable workflows and OCR also require a task-quality policy for a calibrated pick;
+throughput alone does not establish job accuracy. The selected model and note remain visible, and
+caller-supplied fields still win.
+
+`freellama bench-all` explicitly measures installed models and writes
+`$FREELLAMA_HOME/benchmark-report.json` by default (normally
+`~/.octocode/freellama/benchmark-report.json`). On its next start, `serve` discovers that report;
+`FREELLAMA_BENCHMARK_REPORT` can select another file. Only matching schema-2 host/hardware,
+endpoint and artifact-digest evidence qualifies throughput. CPU-assigned runners do not reuse
+the primary endpoint's report. See [machine calibration](../../docs/MODEL_SELECTION.md#turn-measurements-into-routing-evidence)
+for the complete procedure, policy files and evidence limits.
+
+Host-memory admission defaults to `require-memory` on Linux, macOS and Windows. Windows uses a
+bounded PowerShell/CIM query; CPU load, OS pressure, thermal, swap and GPU telemetry remain
+unavailable there. Failed memory observation holds local work, and `require-all` cannot be
+satisfied by the Windows collector. See [resource controls](../../docs/CLI.md#bound-admission)
+for explicit operator policy overrides.
+
+## Research model and sweeps
+
+Without `model` (and without `FREELLAMA_MCP_DEFAULT_MODEL`), `delegate_research` uses the first
+research-agent catalog pick (stronger, default, small) that is installed and fits in memory now;
+GitHub research skips the small pick, which scored 1 of 6 there. When none fits, it takes the
+installed default (then stronger) pick and lets serve's memory gate admit, wait or refuse the load;
+with no pick installed it falls back to routing. The receipt's `researchModel` says which and why.
+GitHub answers are grounded against the adapter's own `gh` results; local adapters check the workspace on disk. A sweep whose
+server process exited reports `interrupted` with the `sweep{action:"resume", sweepId}` call, which
+reuses saved chunk results; sweeps never resume on their own.
+
+## Where an answer goes
+
+Every result is saved whole (`response_file`; read one part with `read_response{file, section}`).
+
+`run_task` and `task_jobs` answer with **text alone**: the answer, its `check:` lines and a closing
+`response_file: <path>` line, with no `structuredContent`. Hosts such as Claude Code show
+`structuredContent` in place of the text when a result has it, which handed the agent the whole
+receipt (1–3k tokens) around a two-line answer. The receipt (route, model, timings, placement,
+tokens) stays in the response file, one `read_response` away; `receipt:"full"` on a call returns it
+inline, and `FREELLAMA_MCP_RECEIPT=structured` restores inline receipts for every call (those two
+tools then declare their output schema again). The other tools always return `structuredContent`.
+`run_task` and `delegate_research` take two more fields that choose what comes back inline:
+
+- `output`: `auto` (default) returns the answer inline up to 8,000 characters (about 2,000 tokens),
+  and above that a short view: the label line, the first lines of the answer, every `check:`,
+  `handoff_file:`, `verification:` and `cited:` line unchanged, and the file holding the whole
+  answer. `inline` always returns the whole text; `file` always returns the short view. The
+  default exists because hosts limit tool output (Claude Code warns above 10,000 tokens and caps
+  it at 25,000 by default) and every inline character costs the calling agent tokens.
+  A shortened view also replaces the answer's text inside `structuredContent` with
+  `answer moved: <output_file or read_response location>` and adds `output: {mode, chars, file}`.
+- `outputPath`: also write the answer there as Markdown (the `saveAs` handoff format), returned as
+  `output_file`. The caller owns the path: a new file is created and an existing one replaced. It
+  must resolve inside the readable roots (the project, the temp directory, `FREELLAMA_FILE_ROOTS`),
+  outside any `.git` directory, and not be a directory. It is checked before the model runs, so it
+  is refused with `preview` or `defer`; with `tasks` one file holds the combined text. A failed
+  write keeps the whole answer inline and names the error.
+
+A shortened view without an `outputPath` writes the answer to a new
+`${FREELLAMA_HOME}/tmp/<timestamp>-<pid>-<n>.md` (default `~/.octocode/freellama`) and ends with
+`output_file: <path> (the full answer, N chars)`; a later `run_task{files:[output_file]}` can read
+it. Those files are deleted after `FREELLAMA_RESPONSE_TTL_DAYS` (default 7; `0` keeps them). If
+that write fails, the view points at the saved response
+(`read_response{file, section:"/result/content/0/text"}`); with neither, the whole answer is
+returned with a note.
+
+`task_jobs{action:"get"}` shapes a finished deferred job the same way (its own `output`, default
+`auto`). Receipts keep the routing, timing and token counts inline; telemetry and nested metrics move
+to the saved `response_file`. `models{view:"installed"}` and `resident` return a slim per-model set;
+`includeVerbose:true` returns the full records.

package/DEVELOPING.md

@@ -2,6 +2,10 @@
 
 Build, test, and release notes for the [FreeLlama MCP server](README.md).
 
+Published npm installs require Node.js 22+ and use a prebuilt platform package; they do not compile
+Rust. This guide's build commands are for repository development. Use the repository's pinned
+Rust toolchain and Node.js 22.12+ with Corepack for source builds.
+
 ## Build
 
 Build the native addon from the repository root and this package in place.
@@ -13,11 +17,14 @@ yarn install
 yarn build
 ```
 
-`yarn build` writes the MCP server, `packages/mcp/dist/index.js` (shebang, executable). During
+`yarn build` writes the MCP server, `packages/mcp/dist/index.js` (shebang, executable), and the
+agent CLI, `dist/agent-cli.js` (the `freellama run`, `chat`, `gateway`… commands, which the CLI package's launcher runs). 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. The research adapters compile to `dist/research/{bash-agent,octocode-agent}.js`, and the
-repository `docs/` guides are copied into `docs/`.
+portable. The research adapters compile to `dist/research/{bash,octocode,github,coder}-agent.js`, and the
+repository `docs/` guides are copied into `docs/`. MCP tools are registered from
+`src/tools/registrations.ts`, which both `src/index.ts` and the agent CLI registry
+(`src/agent-cli/registry.ts`) use, so the two surfaces expose the same tools.
 
 Piecewise, if you are iterating on one layer:
 
@@ -25,7 +32,7 @@ Piecewise, if you are iterating on one layer:
 # 1. Native addon → packages/mcp/native/freellama.<triple>.node
 yarn build:native
 
-# 2. This server → dist/index.js and dist/research/*.js via esbuild, plus docs/
+# 2. This server → dist/index.js, dist/agent-cli.js and dist/research/*.js via esbuild, plus docs/
 yarn workspace @octocodeai/freellama-mcp-server build
 ```
 
@@ -45,12 +52,26 @@ Vitest, in three tiers (all TypeScript, under `test/`):
 |---|---|---|---|
 | `test/unit/` | `yarn test` (watch: `yarn test:watch`) | pure functions straight from `src/*.ts` — no build step, this is the TDD loop | nothing, a few seconds |
 | `test/integration/` | `yarn test:integration` | the built server over the real MCP protocol: tool contract, structured content, guardrails; rebuilds `dist/` itself | Ollama at `FREELLAMA_OLLAMA_ENDPOINT` (default :11434) |
-| `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 |
+| `test/e2e/` | `yarn test:e2e` | live routing/execution, delegated research and an explicitly approved pull → delete round trip | serve + Ollama + models; lifecycle test additionally requires exact tag/size opt-in |
 
 The same commands work from the repository root (`yarn test` there also runs the CLI package's tests
 and the Rust suite).
 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.
+test refuses to delete a model already installed on the test system. The lifecycle opt-in variables
+and readiness skips are documented in [test tiers](../../docs/TESTING.md#run-the-test-tiers).
+
+[CI](../../.github/workflows/ci.yml) configures build, typecheck and Rust contracts on Ubuntu,
+macOS and Windows. Ubuntu/macOS run the full JS/evaluation suite; Windows runs an explicit portable
+CLI/protocol/checker allowlist, excluding the POSIX research/coder and script suites. This does not
+qualify native Windows research/coder execution. Strict Rust lint runs on Ubuntu; release packaging
+contracts run on Ubuntu/macOS; Windows adds a read-only PowerShell/CIM memory smoke. Inspect the hosted run before
+claiming a lane passed. The local macOS checks recorded in [Testing](../../docs/TESTING.md#continuous-integration)
+do not replace those runs or live inference qualification.
+
+The Rust benchmark unit tests now live in `packages/rust-core/src/model_bench/tests.rs`; Windows
+parser fixtures and resource panic/poison tests have separate modules. `job-calibration.test.ts`
+checks calibrated-first selection and fallback without inference. The
+[resource audit](../../docs/RUST_RESOURCE_AUDIT.md) states the lock review's scope and gaps.
 
 For default-endpoint autostart, the server starts `freellama serve` in the background at launch and
 logs a failure to stderr. On a tool call, a spawn failure, early exit, or readiness timeout rejects the
@@ -65,11 +86,15 @@ package has one npm optional dependency per platform in `scripts/release-platfor
 arm64, Linux arm64/x64 with glibc, 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 every artifact package passes
 the publish verifier; an installation made with `--omit=optional` cannot load the addon. `engines`
-requires Node >= 20.
+requires Node >= 22. The matrix currently contains five targets; macOS x64 and Linux musl are not
+published targets. A successful host build does not validate another target or registry install.
 
 Machine discovery distinguishes total host memory (`memory_bytes`) from known unified memory
 (`memory_kind: "unified"`). Library-tag `fitsInMemory` is a conservative host-memory preflight and
 includes `fitScope: "host_memory_budget_only"`; inspect `/api/ps` for actual accelerator placement.
+Windows host admission now requires bounded CIM memory telemetry by default; missing pressure,
+CPU-load, thermal and GPU measurements stay unknown. Parser fixtures run on every host, while the
+Windows CI smoke exercises the real collector.
 
 Start the serve-backed tools' dependency from the repository root:
 
@@ -80,6 +105,10 @@ cargo run --release -- serve
 `freellama proxy` only forwards raw `/api/*` calls; only `serve` has the `/_freellama/v1/*` routes
 these tools call.
 
+Automatic job calibration remains Ollama-backed. The optional managed llama.cpp adapter accepts
+only explicitly configured bounded text tasks and does not supply observed placement, throughput
+qualification or automatic job picks. See the [engine contract](../../docs/LLAMACPP.md).
+
 ## Publish
 
 `packages/mcp/` is the portable JavaScript package. Its `package.json` lists the platform packages
@@ -102,8 +131,10 @@ Treat `npm publish` as a public release action. Follow the
 - **No routing reimplementation.** `run_task`, `run_task {preview:true}`, and the installed-model list are HTTP
   calls into a running `freellama serve`, matching the CLI requests in `packages/cli/src/requests.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 decisions still live in exactly one place — the Rust core; see
-  [what the MCP layer computes](README.md#what-the-mcp-layer-computes).
+  is a subprocess. Routing decisions still live in exactly one place — the Rust core; the MCP layer validates
+  request shapes and derives display fields such as answer text, resident placement labels, library
+  `fitsInMemory` and the research verdict. See the
+  [responsibility boundary](https://github.com/bgauryy/FreeLlama/blob/main/docs/ARCHITECTURE.md#responsibility-boundary).
 - **One connection pool.** `packages/rust-core/src/serve_client.rs` holds a single `reqwest::Client` in a
   `OnceLock` and clones the handle per request; `napi.rs` and the CLI share it.
 - **`unsafe_code` stays isolated.** The crate is `deny(unsafe_code)` except `napi.rs`, which