javis 0.2.0__tar.gz

javis-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

javis-0.2.0/NOTICE

@@ -0,0 +1,4 @@
+JAVIS — harness-governed coding agent
+Copyright 2026 Okello Solomon Roy Jasper
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).

javis-0.2.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: javis
+Version: 0.2.0
+Summary: Joint Autonomous Verified Intelligence System — harness-governed coding agent; intelligence in the harness, not the model
+Author: Okello Solomon Roy Jasper
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0; extra == "llm"
+Requires-Dist: tenacity; extra == "llm"
+Provides-Extra: lsp
+Requires-Dist: python-lsp-server; extra == "lsp"
+Requires-Dist: pyflakes; extra == "lsp"
+Provides-Extra: treesitter
+Requires-Dist: tree-sitter-language-pack>=0.20; extra == "treesitter"
+Provides-Extra: tui
+Requires-Dist: rich>=13; extra == "tui"
+Requires-Dist: prompt_toolkit>=3; extra == "tui"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# JAVIS — Joint Autonomous Verified Intelligence System
+
+A harness-governed coding agent. The name is the thesis: intelligence is **joint** —
+the model is an untrusted prover, the harness a sound proof checker, and neither is the
+agent alone — and every claim is **verified**: the gates refuse to advance on anything
+the tests, parser, or resolver can't confirm. **Put the execution intelligence in the
+harness, not the model.** See [`docs/harness-contract.md`](docs/harness-contract.md).
+
+Created by **Okello Solomon Roy Jasper**.
+
+## Quickstart
+
+```bash
+git clone https://github.com/Code-weaver1/javis.git && cd javis
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[llm,tui]"
+
+export OPENROUTER_API_KEY=sk-or-...   # any OpenRouter key — free-tier models are enough
+javis --check                         # preflight: validates your model ladder against the live catalog
+javis --tui --repo /path/to/your/project --task "fix the failing test"
+```
+
+No API key yet? Watch the harness narrate a three-step gated task behind a scripted model —
+no network, no account:
+
+```bash
+python scripts/tui_narration_demo.py --delay 0.4
+```
+
+Prefer a guided setup (pick a provider, model, and key interactively)? `javis --setup`.
+
+## Status: v1 — a trustworthy correctness engine
+
+The `plan → propose → adjudicate → admit` loop with an **enforced gate set** —
+**0** (plan-shape), **1** (resolve — rejects hallucinated calls), **2/2b** (read-before-write /
+read-verbatim), **3** (parse), **6** (test), **7** (oracle-integrity — the test oracle is read-only) —
+plus a **tiered router** (escalate to a strong tier on failure), a **difficulty-graded fixture
+suite**, `--sandbox` runs, and tier-labeled trajectory logging. Self-planning is off by default
+(Phase 0 showed it hurts; opt in with `--plan`).
+
+**Honest scope:** the harness guarantees **correctness** — it never ships broken or regressing
+code, and the oracle can't be gamed — but it does **not** by itself lift a weak model's *completion
+rate* on reasoning-hard tasks (that's the router + distillation). See `docs/harness-contract.md` §7.
+Growth still ahead: lint/type gates (4/5), coherence + `arch-spec` (8), distillation *training* (P5).
+
+**Reliability layer** (adapted from [Hermes](https://github.com/NousResearch/hermes-agent)): tool-loop
+guardrails (halt-and-escalate on thrash), tool-call JSON repair for weak models, a structured API
+error taxonomy driving router escalation, and a rate-limit cooldown guard so a 429'd model is skipped
+rather than hammered.
+
+**Cost & caching (provider-agnostic).** No provider-specific caching code. The loop keeps a byte-stable
+prompt prefix (system + task) across turns, so providers that auto-cache prefixes (OpenAI, DeepSeek,
+Gemini, most via OpenRouter) apply the discount for free; the one provider that needs explicit
+`cache_control` markers (Anthropic) is handled by litellm when you opt in with `--cache` (off by
+default), never by branching in JAVIS. Context
+compression trims the non-cacheable tail. Net cost levers, all agnostic: stable prefix → auto-cache,
+compression, and escalating to the expensive tier only on failure.
+
+**Extending JAVIS** (provider-agnostic, opt-in — see [`docs/extensibility.md`](docs/extensibility.md)):
+project context (`JAVIS.md`), declarative policy (`.javis-policy.json`), lifecycle hooks
+(`.javis/hooks.json`), reusable commands (`.javis/commands/`), and read-only subagents the main
+agent can delegate to (`.javis/agents/`). Autonomous sandboxing recipe in
+[`docs/autonomous-sandbox.md`](docs/autonomous-sandbox.md).
+
+## Layout
+
+```
+javis/
+  loop.py        plan -> propose -> adjudicate -> admit
+  plan.py        plan stage + plan-shape gate (gate 0)
+  context.py     context window + read-set / read-content (gates 2, 2b)
+  model.py       Model protocol; ScriptedModel (tests/control) + LiteLLMModel (OpenRouter)
+  router.py      tiered escalation (cheap -> strong on failure / API error)
+  guardrails.py  loop detection — halt a thrashing run so the router escalates
+  sanitize.py    repair malformed tool-call JSON from weak models
+  errors.py      API error taxonomy (rate_limit / billing / not_found / ...)
+  ratelimit.py   x-ratelimit header parse + file-based cooldown guard
+  budget.py      run budget
+  trajectory.py  day-0 tier-labeled distillation capture
+  experiment.py  the de-risk matrix runner (models x conditions x fixtures)
+  distill.py     export gate-passed trajectories as tier-labeled SFT data (P5)
+  failure_memory.py  mine recurring failures -> guardrail-hint candidates
+  catalog.py     pick tool-capable / cheap OpenRouter models
+  hooks.py       lifecycle hooks (PreTool/PostTool/Stop scripts)
+  commands.py    markdown task templates (--command / /name)
+  subagents.py   read-only specialized agents (delegate + PARALLEL dispatch); built-in reviewer
+  repomap.py     symbol-level repo map (files + their defs/classes)
+  planmode.py    human-approved plan mode (REPL /plan)
+  tools/git.py   git awareness (status/diff/log) + commit-on-success
+  tools/         fs (read/edit), code (grep/resolve), tests (the pytest oracle)
+  gates/         resolve (1), readwrite (2/2b), parse (3), verify (6), oracle (7), policy, base
+  cli.py         REPL + --headless + --sandbox + --strong-model + --cache + --command + --agent
+                 + --commit + --review + --lint + --types + --map; REPL /plan
+fixtures/        difficulty-graded suite L1-L6 (see fixtures/SUITE.md) + suite.json
+tests/           JAVIS's own suite (the harness verifies itself)
+docs/            harness-contract.md
+```
+
+## Maturity
+
+JAVIS has a **stable core** and a wider **experimental surface**. Both are covered by the test suite,
+but the core is what the correctness guarantees rest on and what every run exercises; the experimental
+modules are iterated less often, change faster, and are not on the correctness path.
+
+- **Stable core** — the loop and gates (`loop.py`, `gates/`, `tools/`), the model/provider layer
+  (`model.py`, `router.py`, `errors.py`, `ratelimit.py`), context + planning (`context.py`, `plan.py`,
+  `compress.py`), `guardrails.py`, `narrator.py`, the LSP type gate (`lsp.py`), and the TUI/CLI.
+- **Experimental / research** — the orchestration bake-off (`orchestrate.py`), the distillation
+  pipeline (`distill.py`, `experiment.py`, `failure_memory.py`), the benchmark runners
+  (`swebench*.py`, `polyglot.py`, `eval_ab.py`), and the plugin marketplace (`marketplace.py`,
+  `mcp_install.py`). Useful and tested, but expect rougher edges and faster change.
+
+## Run
+
+```bash
+# JAVIS's own tests (no network, no litellm needed)
+python -m pytest
+
+# Drive a real model against a fixture (needs litellm + OPENROUTER_API_KEY)
+pip install -e ".[llm]"
+export OPENROUTER_API_KEY=...
+javis --headless --repo fixtures/bugfix-01 --task "make the test suite pass" \
+      --model openrouter/meta-llama/llama-3.1-8b-instruct --trajectory run.jsonl
+
+# Run fully local — no cloud, no API bill (Ollama/LM Studio/vLLM). See docs/local-llm.md
+javis --repo . --task "fix the failing test" --local --model ollama/qwen2.5-coder:7b
+```
+
+Local LLMs (incl. models with no native tool-calling) are first-class — see
+[`docs/local-llm.md`](docs/local-llm.md).
+
+```bash
+# First-run setup wizard (pick provider/model, local or a key). See docs/setup.md
+pip install -e ".[tui]"
+javis --setup
+
+# Live terminal UI — splash, welcome panel, working status, slash commands. See docs/tui.md
+javis --tui --repo . --task "fix the failing test"
+```
+
+The agent can run shell commands behind a permission prompt, and renders multi-step plans as a live
+checklist — see [`docs/shell-and-tasks.md`](docs/shell-and-tasks.md).
+
+JAVIS speaks **MCP** — drop in the standard `.mcp.json` and it inherits the whole Model Context Protocol
+tool ecosystem (`javis --mcp`), gated by permission. See [`docs/mcp.md`](docs/mcp.md).
+
+**Plugins** bundle commands + agents + hooks + MCP servers; JAVIS installs them from a git URL or local
+dir, including **Claude-Code-format** plugins — translated to run on *any* model (incl. local). A
+curated **built-in marketplace** ships in the package (`javis --plugin-install code-review`). See
+[`docs/plugins.md`](docs/plugins.md).
+
+**Measure capability** — `javis-eval` is a lite, local, SWE-bench-style scorecard: real bug-fix
+fixtures, reproduce → solve → score *independently* with the test oracle. Headline numbers are
+`resolved/total` and **false-green** (claimed success the tests don't support — a trustworthy harness
+scores zero, and the CLI exits non-zero if any appear). See [`docs/eval.md`](docs/eval.md).
+
+```bash
+javis-eval --strong-model openrouter/anthropic/claude-sonnet-4   # cheap base, escalate on measured failure
+```
+
+For a comparable number, **`javis-swebench`** points the same reproduce → solve → score loop at the
+**SWE-bench format** (real GitHub issues; checkout at `base_commit`, apply `test_patch`, score
+`FAIL_TO_PASS`/`PASS_TO_PASS`). See [`docs/swebench.md`](docs/swebench.md).
+
+### De-risk experiment knobs
+- `--no-gates` — control: disable the harness (still scored by the final suite) to measure the harness's contribution.
+- `--plan` — opt back into the self-planning stage (OFF by default; Phase 0 showed self-planning hurts completion).
+- `--sandbox` — run on a throwaway copy of `--repo`, leaving the original untouched (try the agent on a fixture without mutating it).
+
+## License
+
+[Apache-2.0](LICENSE) © 2026 Okello Solomon Roy Jasper.

javis-0.2.0/README.md

@@ -0,0 +1,172 @@
+# JAVIS — Joint Autonomous Verified Intelligence System
+
+A harness-governed coding agent. The name is the thesis: intelligence is **joint** —
+the model is an untrusted prover, the harness a sound proof checker, and neither is the
+agent alone — and every claim is **verified**: the gates refuse to advance on anything
+the tests, parser, or resolver can't confirm. **Put the execution intelligence in the
+harness, not the model.** See [`docs/harness-contract.md`](docs/harness-contract.md).
+
+Created by **Okello Solomon Roy Jasper**.
+
+## Quickstart
+
+```bash
+git clone https://github.com/Code-weaver1/javis.git && cd javis
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[llm,tui]"
+
+export OPENROUTER_API_KEY=sk-or-...   # any OpenRouter key — free-tier models are enough
+javis --check                         # preflight: validates your model ladder against the live catalog
+javis --tui --repo /path/to/your/project --task "fix the failing test"
+```
+
+No API key yet? Watch the harness narrate a three-step gated task behind a scripted model —
+no network, no account:
+
+```bash
+python scripts/tui_narration_demo.py --delay 0.4
+```
+
+Prefer a guided setup (pick a provider, model, and key interactively)? `javis --setup`.
+
+## Status: v1 — a trustworthy correctness engine
+
+The `plan → propose → adjudicate → admit` loop with an **enforced gate set** —
+**0** (plan-shape), **1** (resolve — rejects hallucinated calls), **2/2b** (read-before-write /
+read-verbatim), **3** (parse), **6** (test), **7** (oracle-integrity — the test oracle is read-only) —
+plus a **tiered router** (escalate to a strong tier on failure), a **difficulty-graded fixture
+suite**, `--sandbox` runs, and tier-labeled trajectory logging. Self-planning is off by default
+(Phase 0 showed it hurts; opt in with `--plan`).
+
+**Honest scope:** the harness guarantees **correctness** — it never ships broken or regressing
+code, and the oracle can't be gamed — but it does **not** by itself lift a weak model's *completion
+rate* on reasoning-hard tasks (that's the router + distillation). See `docs/harness-contract.md` §7.
+Growth still ahead: lint/type gates (4/5), coherence + `arch-spec` (8), distillation *training* (P5).
+
+**Reliability layer** (adapted from [Hermes](https://github.com/NousResearch/hermes-agent)): tool-loop
+guardrails (halt-and-escalate on thrash), tool-call JSON repair for weak models, a structured API
+error taxonomy driving router escalation, and a rate-limit cooldown guard so a 429'd model is skipped
+rather than hammered.
+
+**Cost & caching (provider-agnostic).** No provider-specific caching code. The loop keeps a byte-stable
+prompt prefix (system + task) across turns, so providers that auto-cache prefixes (OpenAI, DeepSeek,
+Gemini, most via OpenRouter) apply the discount for free; the one provider that needs explicit
+`cache_control` markers (Anthropic) is handled by litellm when you opt in with `--cache` (off by
+default), never by branching in JAVIS. Context
+compression trims the non-cacheable tail. Net cost levers, all agnostic: stable prefix → auto-cache,
+compression, and escalating to the expensive tier only on failure.
+
+**Extending JAVIS** (provider-agnostic, opt-in — see [`docs/extensibility.md`](docs/extensibility.md)):
+project context (`JAVIS.md`), declarative policy (`.javis-policy.json`), lifecycle hooks
+(`.javis/hooks.json`), reusable commands (`.javis/commands/`), and read-only subagents the main
+agent can delegate to (`.javis/agents/`). Autonomous sandboxing recipe in
+[`docs/autonomous-sandbox.md`](docs/autonomous-sandbox.md).
+
+## Layout
+
+```
+javis/
+  loop.py        plan -> propose -> adjudicate -> admit
+  plan.py        plan stage + plan-shape gate (gate 0)
+  context.py     context window + read-set / read-content (gates 2, 2b)
+  model.py       Model protocol; ScriptedModel (tests/control) + LiteLLMModel (OpenRouter)
+  router.py      tiered escalation (cheap -> strong on failure / API error)
+  guardrails.py  loop detection — halt a thrashing run so the router escalates
+  sanitize.py    repair malformed tool-call JSON from weak models
+  errors.py      API error taxonomy (rate_limit / billing / not_found / ...)
+  ratelimit.py   x-ratelimit header parse + file-based cooldown guard
+  budget.py      run budget
+  trajectory.py  day-0 tier-labeled distillation capture
+  experiment.py  the de-risk matrix runner (models x conditions x fixtures)
+  distill.py     export gate-passed trajectories as tier-labeled SFT data (P5)
+  failure_memory.py  mine recurring failures -> guardrail-hint candidates
+  catalog.py     pick tool-capable / cheap OpenRouter models
+  hooks.py       lifecycle hooks (PreTool/PostTool/Stop scripts)
+  commands.py    markdown task templates (--command / /name)
+  subagents.py   read-only specialized agents (delegate + PARALLEL dispatch); built-in reviewer
+  repomap.py     symbol-level repo map (files + their defs/classes)
+  planmode.py    human-approved plan mode (REPL /plan)
+  tools/git.py   git awareness (status/diff/log) + commit-on-success
+  tools/         fs (read/edit), code (grep/resolve), tests (the pytest oracle)
+  gates/         resolve (1), readwrite (2/2b), parse (3), verify (6), oracle (7), policy, base
+  cli.py         REPL + --headless + --sandbox + --strong-model + --cache + --command + --agent
+                 + --commit + --review + --lint + --types + --map; REPL /plan
+fixtures/        difficulty-graded suite L1-L6 (see fixtures/SUITE.md) + suite.json
+tests/           JAVIS's own suite (the harness verifies itself)
+docs/            harness-contract.md
+```
+
+## Maturity
+
+JAVIS has a **stable core** and a wider **experimental surface**. Both are covered by the test suite,
+but the core is what the correctness guarantees rest on and what every run exercises; the experimental
+modules are iterated less often, change faster, and are not on the correctness path.
+
+- **Stable core** — the loop and gates (`loop.py`, `gates/`, `tools/`), the model/provider layer
+  (`model.py`, `router.py`, `errors.py`, `ratelimit.py`), context + planning (`context.py`, `plan.py`,
+  `compress.py`), `guardrails.py`, `narrator.py`, the LSP type gate (`lsp.py`), and the TUI/CLI.
+- **Experimental / research** — the orchestration bake-off (`orchestrate.py`), the distillation
+  pipeline (`distill.py`, `experiment.py`, `failure_memory.py`), the benchmark runners
+  (`swebench*.py`, `polyglot.py`, `eval_ab.py`), and the plugin marketplace (`marketplace.py`,
+  `mcp_install.py`). Useful and tested, but expect rougher edges and faster change.
+
+## Run
+
+```bash
+# JAVIS's own tests (no network, no litellm needed)
+python -m pytest
+
+# Drive a real model against a fixture (needs litellm + OPENROUTER_API_KEY)
+pip install -e ".[llm]"
+export OPENROUTER_API_KEY=...
+javis --headless --repo fixtures/bugfix-01 --task "make the test suite pass" \
+      --model openrouter/meta-llama/llama-3.1-8b-instruct --trajectory run.jsonl
+
+# Run fully local — no cloud, no API bill (Ollama/LM Studio/vLLM). See docs/local-llm.md
+javis --repo . --task "fix the failing test" --local --model ollama/qwen2.5-coder:7b
+```
+
+Local LLMs (incl. models with no native tool-calling) are first-class — see
+[`docs/local-llm.md`](docs/local-llm.md).
+
+```bash
+# First-run setup wizard (pick provider/model, local or a key). See docs/setup.md
+pip install -e ".[tui]"
+javis --setup
+
+# Live terminal UI — splash, welcome panel, working status, slash commands. See docs/tui.md
+javis --tui --repo . --task "fix the failing test"
+```
+
+The agent can run shell commands behind a permission prompt, and renders multi-step plans as a live
+checklist — see [`docs/shell-and-tasks.md`](docs/shell-and-tasks.md).
+
+JAVIS speaks **MCP** — drop in the standard `.mcp.json` and it inherits the whole Model Context Protocol
+tool ecosystem (`javis --mcp`), gated by permission. See [`docs/mcp.md`](docs/mcp.md).
+
+**Plugins** bundle commands + agents + hooks + MCP servers; JAVIS installs them from a git URL or local
+dir, including **Claude-Code-format** plugins — translated to run on *any* model (incl. local). A
+curated **built-in marketplace** ships in the package (`javis --plugin-install code-review`). See
+[`docs/plugins.md`](docs/plugins.md).
+
+**Measure capability** — `javis-eval` is a lite, local, SWE-bench-style scorecard: real bug-fix
+fixtures, reproduce → solve → score *independently* with the test oracle. Headline numbers are
+`resolved/total` and **false-green** (claimed success the tests don't support — a trustworthy harness
+scores zero, and the CLI exits non-zero if any appear). See [`docs/eval.md`](docs/eval.md).
+
+```bash
+javis-eval --strong-model openrouter/anthropic/claude-sonnet-4   # cheap base, escalate on measured failure
+```
+
+For a comparable number, **`javis-swebench`** points the same reproduce → solve → score loop at the
+**SWE-bench format** (real GitHub issues; checkout at `base_commit`, apply `test_patch`, score
+`FAIL_TO_PASS`/`PASS_TO_PASS`). See [`docs/swebench.md`](docs/swebench.md).
+
+### De-risk experiment knobs
+- `--no-gates` — control: disable the harness (still scored by the final suite) to measure the harness's contribution.
+- `--plan` — opt back into the self-planning stage (OFF by default; Phase 0 showed self-planning hurts completion).
+- `--sandbox` — run on a throwaway copy of `--repo`, leaving the original untouched (try the agent on a fixture without mutating it).
+
+## License
+
+[Apache-2.0](LICENSE) © 2026 Okello Solomon Roy Jasper.

javis-0.2.0/javis/__init__.py

@@ -0,0 +1,7 @@
+"""JAVIS — a harness-governed coding agent.
+
+Phase 0 thesis: the intelligence is in the harness, not the model. The model is an
+untrusted prover; the harness is a sound proof checker. See docs/harness-contract.md.
+"""
+
+__version__ = "0.0.0"

javis-0.2.0/javis/_banner.py

@@ -0,0 +1,69 @@
+"""Generated by scripts/gen_banner.py from the JAVIS logo. Do not edit by hand.
+HERO/LOGO are rich markup (crimson scorpion / white shield); *_PLAIN strip the tags."""
+
+HERO = r'''
+                      [#f5f5f5]▒▓▓▒▒[/] [#e10600]▓█████▓[/]       [#e10600]▓█████▒[/] [#f5f5f5]▒▓▓▓▒[/]
+                   [#f5f5f5]▓██▓[/] [#e10600]▒██████▓[/] [#e10600]▒▓[/]       [#e10600]▓▒[/] [#e10600]▓██████▓[/] [#f5f5f5]▓██▓[/]
+                  [#f5f5f5]█▓[/] [#e10600]▒▓███████▓███▒[/] [#e10600]██[/] [#e10600]▓█[/] [#e10600]▒███▓████████[/]  [#f5f5f5]▓█▒[/]
+                  [#f5f5f5]▓█[/]  [#e10600]▓▓▓████▓██▓[/]   [#e10600]█████[/]   [#e10600]▒██▓█████▓█▓[/] [#f5f5f5]█▓[/]
+                   [#f5f5f5]▓█[/] [#e10600]████▓[/]    [#e10600]▒██▒███████▒██▒[/]    [#e10600]▓████[/] [#f5f5f5]▓▓[/]
+                    [#f5f5f5]▓▓[/] [#e10600]█████[/] [#e10600]▒████▓████████▓███▓[/] [#e10600]█████[/] [#f5f5f5]▓▓[/]
+                     [#f5f5f5]▒▒[/] [#e10600]████▓████▓█████████▓████▓▓███[/]  [#f5f5f5]▒[/]
+                         [#e10600]██▒████▒[/] [#e10600]▓████████[/] [#e10600]▒▓███▒██[/]
+                            [#e10600]▒[/]   [#e10600]▒[/]  [#e10600]▓█████▓[/]      [#e10600]▒[/]
+                             [#e10600]▒██▓[/]  [#e10600]█▓▓▓▒██[/]
+                             [#e10600]▓███▓[/]  [#e10600]█████▓[/]
+                              [#e10600]▓██▓[/]   [#e10600]▓██▓███[/]
+                             [#f5f5f5]▒[/][#e10600]▒████[/]    [#e10600]▓████▒[/]  [#f5f5f5]▒[/]
+                             [#f5f5f5]▒▓[/]  [#e10600]▓█▓█▓[/] [#e10600]▓███▓[/]  [#f5f5f5]▓▒[/]
+                               [#f5f5f5]▓▓[/] [#e10600]▓███▒███▓[/] [#f5f5f5]▓▓[/]
+                                [#f5f5f5]▒█▓[/] [#e10600]▓█▓█▓[/] [#f5f5f5]▒█▓[/]
+                                  [#f5f5f5]▓█▓[/]   [#f5f5f5]▒█▓[/]
+                                   [#f5f5f5]▒██▓██▒[/]
+                                     [#f5f5f5]▒█▒[/]
+'''
+
+HERO_PLAIN = r'''
+                      ▒▓▓▒▒ ▓█████▓       ▓█████▒ ▒▓▓▓▒
+                   ▓██▓ ▒██████▓ ▒▓       ▓▒ ▓██████▓ ▓██▓
+                  █▓ ▒▓███████▓███▒ ██ ▓█ ▒███▓████████  ▓█▒
+                  ▓█  ▓▓▓████▓██▓   █████   ▒██▓█████▓█▓ █▓
+                   ▓█ ████▓    ▒██▒███████▒██▒    ▓████ ▓▓
+                    ▓▓ █████ ▒████▓████████▓███▓ █████ ▓▓
+                     ▒▒ ████▓████▓█████████▓████▓▓███  ▒
+                         ██▒████▒ ▓████████ ▒▓███▒██
+                            ▒   ▒  ▓█████▓      ▒
+                             ▒██▓  █▓▓▓▒██
+                             ▓███▓  █████▓
+                              ▓██▓   ▓██▓███
+                             ▒▒████    ▓████▒  ▒
+                             ▒▓  ▓█▓█▓ ▓███▓  ▓▒
+                               ▓▓ ▓███▒███▓ ▓▓
+                                ▒█▓ ▓█▓█▓ ▒█▓
+                                  ▓█▓   ▒█▓
+                                   ▒██▓██▒
+                                     ▒█▒
+'''
+
+LOGO = r'''
+           [#e10600]▓▒[/]   [#e10600]▓[/]
+      [#f5f5f5]▒▓[/][#e10600]▓███▓▒▓▒████[/][#f5f5f5]▒▓[/]
+       [#f5f5f5]▓[/][#e10600]██▓██████▓██▒[/][#f5f5f5]▒[/]
+         [#e10600]▓▓█▓███▓█▓▒[/]
+           [#e10600]█▓██▓[/]
+           [#e10600]▓█▓▓█▒[/]
+            [#f5f5f5]▓[/][#e10600]▓▓[/][#f5f5f5]▓▒[/]
+             [#f5f5f5]▒▓[/]
+'''
+
+LOGO_PLAIN = r'''
+           ▓▒   ▓
+      ▒▓▓███▓▒▓▒████▒▓
+       ▓██▓██████▓██▒▒
+         ▓▓█▓███▓█▓▒
+           █▓██▓
+           ▓█▓▓█▒
+            ▓▓▓▓▒
+             ▒▓
+'''
+