spillway-mcp
# `spillway-mcp` — Multi-provider inference router
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](#)
[](https://opensource.org/licenses/Apache-2.0)
## v1.4: read-only Codex bridge (Temporary Interim Release — v2 Rewrite Pending)
> **Status Notice:** `v1.4` is a **temporary interim update** that adds read-only Codex CLI capabilities to the existing `v1` server architecture for immediate use. A **full `v2` architectural rewrite** (persistent out-of-process supervisor, staged artifact isolation, OS-enforced containment, and a unified multi-provider execution control plane) is pending and will supersede the `v1.x` runtime.
Claude Code remains the orchestrator and owns task decomposition, acceptance, and commits. Codex adds independent research, debugging analysis, and code review through five tools:
| Tool | Purpose |
|---|---|
| `codex_research` | Start read-only research with an explicit model and reasoning effort. |
| `codex_followup` | Resume a completed Spillway session by explicit `session_id`, in the same workspace/home and model. |
| `codex_job_result` | Inspect or wait for a `job_id`. |
| `codex_status` | Inspect setup, queue, configured model, and quota uncertainty without inference. |
| `codex_cancel` | Request cancellation and wait for stop evidence; never pre-approved as read-only. |
Codex and agy have independent queues, one worker each. Cross-provider reads may overlap. Cooperating agy edits, local test commands, and local draft writes exclude both providers' reads. Local draft application checks for target drift after inference and refuses stale overwrites. **Run only one Spillway server against a shared workspace/provider home in v1.** These are in-process coordination rules, not machine-wide locks or protection from editor saves.
### Setup
The current compatibility pin is **`codex-cli 0.166.0-alpha.5.1`**, verified on Windows. Other CLI versions fail explicitly until their config and sandbox behavior is validated. Node remains `>=18`; there are no new npm runtime dependencies. Native macOS/Linux execution has not been certified by this Windows test run.
1. Use the pinned native Codex binary, or set `SPILLWAY_CODEX_BIN` to a native executable or the npm package's `bin/codex.js`. Standard npm Windows wrappers resolve to that Node entrypoint; the server does not execute wrappers through a shell.
2. Optionally set `SPILLWAY_CODEX_HOME` to a dedicated directory. Its default is `config/codex-runtime/home` beneath `AGY_CONFIG_DIR`. Do not use your normal `~/.codex` home. Use the same settings for setup and the MCP server.
3. Run `npm run codex:login` interactively. This explicitly signs in with ChatGPT into the dedicated home, using file credential storage. Startup never copies credentials or triggers login. The helper does not change the parent process's environment or ordinary Codex config.
4. Set `SPILLWAY_CODEX_MODEL` to an exact model slug available to your account, or supply `model` on a research call. No model is guessed. Add these `SPILLWAY_CODEX_*` settings to the server's MCP environment when launching from an IDE.
5. Call `codex_status`, then `codex_research` with `prompt`, optional `model`, `effort` (`low`, `medium`, `high`, `xhigh`), `cwd`, and `wait_ms`. Model/effort availability depends on the account; unsupported selections fail without fallback. `wait_ms: 0` returns a handle immediately; default/max wait is 540 seconds. The worker watchdog is 30 minutes.
The child ignores user config and execpolicy files, marks its project untrusted, disables MCP/app/plugin/subagent/hook delegation, and pins read-only execution with approvals disabled. Windows uses the unelevated sandbox. Prompts go through stdin, never shell interpolation. Ambient API keys, Codex overrides and Node injection settings are not forwarded. The bridge pins ChatGPT authentication and has **no automatic API billing, effort, model, or cross-provider fallback**. Administrator-managed restrictions still apply; a refusal is not worked around. See [Codex non-interactive execution](https://learn.chatgpt.com/docs/non-interactive-mode) and the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
`ok` means a zero-exit, valid completed CLI turn with nonempty text and a matching final artifact. It does not certify the answer or task success. Jobs record the explicitly requested model/effort, CLI version, prompt hash, usage as reported, session, output, and stop evidence. Account quota remains unknown. Filesystem reads are live; read-only is not a confidentiality boundary around the workspace. For independent review, pass source/diff, requirements and test evidence, withholding the author's rationale yourself; mechanical blinding and immutable artifact review are v2 features.
### Validation and recovery
`npm test` exercises mock providers, stream parsing, lifecycle failures, workspace coordination, and MCP framing without cloud inference. `npm run test:codex-canary` separately exercises the installed CLI against a loopback fake Responses provider, including explicit resume. The Windows canary verified a file read, denied writes inside/outside the workspace, and no user/project MCP startup. It uses no account credentials or real inference, and stores private proof under `.local/canaries/`.
Codex records and logs live under `config/codex-runtime/` (or the configured runtime config directory). Unconfirmed stops become `quarantined`; lost active ownership on restart becomes `outcome_unknown`. Both block further managed execution. Local commands also leave a conservative recovery marker if execution or termination is unresolved. Do not delete a marker merely because the parent PID is gone: stop all owning server instances and inspect remaining processes before manually resolving retained records. No automatic recovery/clear tool is supplied in v1. Retention is manual; preserve unresolved jobs and session data needed for follow-up.
The package allowlist excludes live credentials, runtime records, and `.local/`. These runtime paths are Git-ignored. Persistent supervisor ownership, stronger containment, staged edits/apply, and automatic recovery remain v2 work.
## 1. Executive Summary
`spillway-mcp` is a **zero-dependency Node.js Model Context Protocol (MCP) server** that connects **Claude Code** (**Opus / Fable / Sonnet**) to **Gemini through agy, read-only Codex CLI, and local GPU inference**. The existing Gemini/local routing tiers remain:
1. **Tier 0 (Apex Orchestrator):** Claude Code (**Opus / Fable / Sonnet**) handles high-level architectural decisions, surgical multi-line `Edit` patches, and final user synthesis.
2. **Tier 1 & 2 (Cloud Subagent Governor — Google Antigravity `agy`):** Routes wide-context exploration, disjoint-directory swarms, and deep multi-file reasoning across **Gemini 3.8 Flash** (`1x–2x` weight) and **Gemini 4 Argon** (`4x–6x` weight) with deterministic 5-hour/weekly quota governance and automatic `429` step-down.
3. **Tier 3 (Local Consumer GPU Context Scrubber — Ollama / `llama-server`):** Intercepts high-volume file reads, verbose test/build logs, and leaf-node boilerplate generation on a local GPU (`0x` cloud quota burn), returning `<300 token` forensic `<file>:<line>` digests so raw file bloat and passing test noise never enter cloud context windows.
In production workflows, this spillway architecture **reduces frontier cloud token consumption by 40–60%** while eliminating mid-session **context rot** and **stale-memory hallucinations**.
---
## 2. Architecture & Data Flow
```text
+-----------------------------------------------------------------------------------+
| TIER 0: FRONTIER ORCHESTRATOR |
| Claude Code (Opus / Fable / Sonnet Session) |
| Receives `ZERO-TRUST MEMORY` & routing rules via MCP `initialize.instructions` |
+-----------------------------------------+-----------------------------------------+
|
| JSON-RPC 2.0 over stdio
v
+-----------------------------------------------------------------------------------+
| SPILLWAY MCP SERVER (`server/index.js`) |
| - Server-side disk reader (raw files & verbose logs never cross MCP arguments) |
| - Single-process execution queues (AGY_MAX_CONCURRENCY=1, LOCAL_GPU_CONCURRENCY=1)|
| - Secret/binary lockout (.env*, id_rsa, first-4KB \0 null-byte detection) |
+-------------------+-------------------------------------------+-------------------+
| |
[Context Scrubbing & Leaf Tasks] [Cross-Module Analysis & Swarms]
`local_file_scout` `agy_delegate_research`
`local_exec_and_triage` `agy_spawn_swarm` (disjoint paths)
`local_draft_leaf_code` `agy_delegate_edit` / `followup`
| |
v v
+---------------------------------------+ +---------------------------------------+
| TIER 3: LOCAL GPU WORKER (0x) | | TIER 1 & 2: GEMINI CLOUD GOVERNOR |
| Local GPU 8-24GB (`127.0.0.1:11434/8080`)| | Google Antigravity CLI (`agy`) |
| - Probes Ollama `/api/ps` (hot VRAM) | | - `argon-high` (6x) -> `argon-med` |
| - 1-based line numbers + 50/50 slice | | -> `argon-low` -> `flash-high` |
| - Forensic `SCOUT_SYSTEM_PROMPT` | | -> `flash-medium` -> `flash-low` |
| - Empty/truncated overwrite guard | | - 80% session context auto-compaction|
+-------------------+-------------------+ +-------------------+-------------------+
| ^
+----- Automatic Zero-Error Spillover ------+
(If local GPU is offline / gaming mode
or payload exceeds VRAM ceiling)
```
---
## 3. Key Engineering Problems Solved
### A. Context Pollution & Cloud Token Burn ("Context Rot")
When a frontier orchestrator (**Opus / Fable / Sonnet**) reads five 800-line source files (`~16,000 tokens`) or runs `pytest` / `npm test` producing 2,500 lines of passing test output (`~25,000 tokens`), those raw tokens remain in the conversation history for **every subsequent turn**.
* **How `spillway-mcp` solves it:** `local_file_scout` and `local_exec_and_triage` read files and execute test runners **on the MCP server side**. The local GPU extracts only the requested `<file>:L<line>` signatures or failing stack traces (`<300 tokens`), keeping 95%+ of raw noise out of the cloud context window.
### B. Zero-Trust Disk Verification (Eliminating Stale-Memory Hallucinations)
In long-running coding sessions (15+ turns), frontier LLMs (**Opus / Fable / Sonnet**) suffer from **recency/memory bias**—answering architectural questions from stale turns rather than re-verifying the disk, or skipping `Read` calls to save context.
* **How `spillway-mcp` solves it:**
1. **Triple-Anchored `ZERO-TRUST MEMORY` Rule:** Injected at Turn 0 via MCP `initialize.instructions`, reinforced in tool schema descriptions, and anchored at the bottom of every tool output in the `[AGY GOVERNOR TELEMETRY]` footer.
2. **Forensic `SCOUT_SYSTEM_PROMPT`:** Instructs the local GPU to report **only** verbatim signatures with 1-based line numbers (`src/auth.ts:L42-L58`), or emit the deterministic sentinel `"NOT_FOUND_ON_DISK: [symbol/query]"` if absent.
### C. Consumer GPU Safeguards (12 GB VRAM Hard Limits)
Running a local LLM on a multipurpose workstation requires strict hardware safeguards:
1. **Ollama `/api/ps` vs. `/v1/models` Trap Guard:** On Ollama (`:11434`), `GET /v1/models` lists *every downloaded model on disk*, which can trigger a 15-second cold load of an oversized model. The router probes `GET /api/ps` first to use the model already hot in VRAM and passes `"keep_alive": "30m"`.
2. **Empty-Output & Truncation Overwrite Guard:** In `local_draft_leaf_code`, if the local model returns `<15` characters, conversational filler, an unclosed markdown code fence (` ``` `), or `finish_reason === "length"`, the server **aborts the disk write**, leaves `target_file` untouched, and escalates to `gemini-3.8-flash-high`.
3. **Windows Process-Tree Reaping (`taskkill /T /F`):** Timed-out test runners request a tree stop. Windows confirmation requires successful `taskkill /T /F` and observed child closure; failed confirmation is reported explicitly. This is ordinary process-tree handling, not escape-proof containment.
4. **50-50 Head/Tail Slicing with Preserved Line Numbers:** Files exceeding the VRAM context budget (`80,000 chars` on 12 GB VRAM) are numbered first (`1: ...`) and sliced 50% head / 50% tail so imports at the top and exports at the bottom retain exact line numbers.
### D. Deterministic Quota & Rate-Limit Governance
* Tracks rolling **5-hour** and **weekly** weighted burn budgets in `config/state-ledger.json` (auto-initialized from `config/state-ledger.example.json`).
* Parses `429 RESOURCE_EXHAUSTED` cooldown timers (`Resets in 1h20m30s`) from `agy` logs, locks the exhausted tier until its reset timestamp, and transparently steps down the fallback chain (`argon-high -> argon-medium -> argon-low -> flash-high -> flash-medium -> flash-low`).
### E. Non-Invasive Security & Least-Privilege Defaults
* **Zero Side Effects on `stdio` Startup:** Starting the MCP server never modifies `CLAUDE.md`, `AGENTS.md`, `.git/config`, or `.claude/settings.local.json`.
* **Least-Privilege Bootstrap:** Running `--bootstrap` never sets `enableAllProjectMcpServers: true` and pre-approves only the 5 read-only tools (`agy_status`, `agy_delegate_research`, `agy_spawn_swarm`, `agy_job_result`, `local_file_scout`).
* **Safe Triage Command Allowlist:** `local_exec_and_triage` blocks shell chaining operators (`&&`, `;`, `|`) and restricts execution to allow-listed test, typecheck, and lint runners.
* **Async Job Handoff & Hard Watchdog (`AGY_SOFT_TIMEOUT_MS` / `AGY_RUN_MAX_MS`):** Every `agy` run is assigned a `job_id` and registered in `sessions` and `agy_process_queue` at launch (`state: "running"`, `started_at`, `elapsed_s`, `tier`, `prompt_preview`). If a run exceeds the soft budget (`AGY_SOFT_TIMEOUT_MS`, default `540000` = 540s, below the 600s MCP client timeout), the tool returns a normal non-error response (`still running, job <id>...; fetch with agy_job_result <id>`) while the child continues in the background, preventing dropped stdio connections. A hard watchdog (`AGY_RUN_MAX_MS`, default `1800000` = 30m) terminates genuinely hung processes and preserves the log path, and `agy_cancel` lets callers abort any in-flight or queued job on demand.
---
## 4. Exposed MCP Tools (11 Tools)
| Tool Name | Tier | Quota Burn | Purpose |
| :--- | :--- | :---: | :--- |
| `local_file_scout` | Tier 3 (Local GPU -> Flash Fallback) | **0x** | Forensic `<file>:L<line>` signature & import extractor (`<300 tokens`). |
| `local_exec_and_triage` | Tier 3 (Local GPU -> Flash Fallback) | **0x** | Runs allow-listed test/build commands; returns `<=40` lines directly or scrubs `>40` lines on GPU. |
| `local_draft_leaf_code` | Tier 3 (Local GPU -> Flash Fallback) | **0x** | Drafts boilerplate/unit tests to disk with truncation guard + `git diff --stat`. |
| `agy_delegate_research` | Tier 1/2 (Gemini Flash / Argon) | **1x–6x** | Read-only codebase investigation (`--mode=plan`) with headless git allow-list rules & 540s soft async handoff. |
| `agy_spawn_swarm` | Tier 1 (Gemini Flash Low/Med) | **1x/task** | Disjoint-directory subagent swarm (serialized sequentially) with path-collision validation. |
| `agy_delegate_edit` | Tier 2 (Gemini Argon / Flash) | **2x–6x** | Scoped multi-file modifications (`--mode=accept-edits`) with optional IDE `--diff` review. |
| `agy_session_followup` | Tier 1/2 (Session Resume) | **1x–6x** | Resumes cached `conversation_id` and auto-compacts at 80% context usage. |
| `agy_job_result` | Utility (Async Job Fetch) | **0x** | Retrieves the stored answer or live elapsed status of an async `job_id` (or `"latest"`). |
| `agy_cancel` | Utility (Queue Control) | **0x** | Cancels a running or queued `job_id` (or `"active"`), waiting for stop evidence; unconfirmed stops quarantine the job and block new agy launches. |
| `agy_configure_workspace` | Utility | **0x** | Auto-detects `.venv` / `node_modules/.bin` and configures optional Antigravity IDE HUD sync. |
| `agy_status` | Utility | **0x** | Reports live GPU VRAM probe, cloud quota timers, active/waiting jobs (`agy_process_queue`), and sessions. |
---
## 5. Quick Start Guide
### Step 1: Clone & Run the Sandboxed Smoke Test
```bash
git clone https://github.com/Secret-art-stack/spillway-mcp.git
cd spillway-mcp
npm test
```
*(`npm test` runs provider, lifecycle, and process-stop regression tests plus `node server/smoke-test.js` inside a disposable `os.tmpdir()` workspace and verifies all offline safeguards, permission rules, and MCP stdio framing).*
### Step 2: Configure Local GPU Inference (Ollama or `llama-server`)
Pick your hardware preset in [`config/model-matrix.json`](./config/model-matrix.json) (`8gb_vram`, `12gb_vram`, or `24gb_vram_or_mac_unified`). For a **12 GB VRAM GPU** with **Ollama**:
```bash
# Enable Flash Attention, 8-bit quantized KV cache, and 16K context window
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
export OLLAMA_CONTEXT_LENGTH=16384
# Pull and warm the default coding model
ollama pull qwen2.5-coder:14b
```
Or with **`llama.cpp` (`llama-server`)** on port `8080`:
```bash
llama-server -m qwen2.5-coder-14b-instruct-q4_k_m.gguf \
--port 8080 --ctx-size 16384 --cache-type-k q8_0 --cache-type-v q8_0 -fa -ngl 99
```
> **Tip:** If running heavy desktop/IDE apps alongside the GPU on a 12 GB card (~6.5–7 GB free VRAM), use a 9B/12B model like `qwen3.5:9b` or `gemma4:12b-q4_K_M` (~5.5–6.5 GB) so weights + KV cache stay 100% in VRAM without PCIe spillover.
### Step 3: Register in Claude Code (`.mcp.json`)
Copy [`.mcp.example.json`](./.mcp.example.json) to `.mcp.json` in your project root (or run `node server/index.js --bootstrap` with user confirmation):
```json
{
"mcpServers": {
"agy-subagent": {
"command": "node",
"args": ["./spillway-mcp/server/index.js"],
"timeout": 600000,
"env": {
"AGY_NO_SELF_BOOTSTRAP": "1",
"AGY_GIT_REPORT_ONLY": "1",
"AGY_DENY_SKIP_PERMISSIONS": "1",
"LOCAL_GPU_PROFILE": "12gb_vram",
"LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434/v1",
"LOCAL_OLLAMA_MODEL": "qwen2.5-coder:14b"
}
}
}
}
```
---
## 6. Repository Structure
```text
spillway-mcp/
├── server/
│ ├── index.js # Zero-dependency MCP server & hybrid routing engine
│ ├── providers/agy.js # Antigravity invocation and response adapter
│ ├── provider-test.js # Offline provider/routing regression tests
│ └── smoke-test.js # Sandboxed test suite (runs in os.tmpdir())
├── config/
│ ├── model-matrix.json # Tiered routing & 8GB / 12GB / 24GB hardware presets
│ ├── state-ledger.example.json
│ └── ide-sync.example.json
├── docs/
│ └── ROUTING_GUIDE.md # Optional @import guide for CLAUDE.md
├── .mcp.example.json # Example MCP registration for Claude Code
├── .gitignore # Ignores live state-ledger.json, ide-sync.json, .env, logs
├── LICENSE # Apache License 2.0
├── package.json # Metadata and offline test scripts
└── README.md # Architectural documentation
```
---
## 7. License
Licensed under the [Apache License, Version 2.0](./LICENSE).
### Execution recovery limits
Running agy cancellation transitions through `terminating`. Confirmed stops become `cancelled` or `timed_out`; unconfirmed stops become `quarantined`. Restarted servers mark unowned active executions `outcome_unknown`. Both unresolved states block new agy launches with `EXECUTION_UNRESOLVED`; they are not automatically pruned or retried. Inspect the recorded job, attempt logs, and remaining processes before resolving ledger records. There is no automatic recovery/clear operation yet; do not clear a record solely because its parent PID is absent.
This v1 gate coordinates agy, Codex, and local writers within one server, not atomic ownership across multiple server processes. Local commands persist an unresolved-execution marker and block further managed work after uncertain termination or restart. Native containment, cross-client scheduling, and recovery controls belong to the v2 supervisor. Retained attempt logs require manual retention management; preserve unresolved-job evidence.
TDQS
Scored across 16 tools
The prefix scheme separates three backends (codex_, agy_, local_), but each backend exposes near-parallel operations — codex_research vs agy_delegate_research, codex_followup vs agy_session_followup, codex_status vs agy_status, codex_cancel vs agy_cancel — so an agent must read the routing rules to pick correctly. Descriptions do a lot of work with explicit 'DO NOT USE FOR' clauses, but the overlapping research/scout/draft/edit triad (local_file_scout vs agy_delegate_research vs local_draft_leaf_code vs agy_delegate_edit) remains genuinely easy to misselect.
A consistent three-prefix scheme (codex_/agy_/local_) groups tools predictably, which is a real strength. Within groups, however, conventions are mixed: verb_noun (agy_delegate_edit, agy_spawn_swarm) sits beside noun-phrase tools (agy_status, agy_job_result, codex_job_result) and odd forms like local_file_scout (noun_verb) and local_exec_and_triage.
Sixteen tools is at the borderline of heavy, and the cost is amplified because the surface duplicates the same lifecycle (research, follow-up, status, cancel, job-result) across two agent backends plus a local tier. Each tool is justified individually, but the aggregate feels larger than the underlying domain requires.
Coverage is broad: research, editing, multi-file delegation, drafting, command execution, session follow-up, job retrieval, cancellation, status, and workspace configuration are all present, so most workflows have a path forward. Minor gaps include no generic file read/list or job-listing operation independent of the status tools, and Codex offers no edit path at all.