raga-cli 0.0.0-stage → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+## [0.9.0](https://github.com/mr-jones123/raga/compare/raga-v0.8.0...raga-v0.9.0) (2026-10-31)
+
+### Features
+
+* add archive compaction strategy that drops context without a summarization call ([3b682ee](https://github.com/mr-jones123/raga/commit/3b682ee878320ce897f136b8661f3b0178c9df1d))
+* add bend and raga-artifacts skills and run peak in ordinary sessions ([4fb5df2](https://github.com/mr-jones123/raga/commit/4fb5df2d32583b6d03f77d5e62c37a219978fcc7))
+* add managed local models and CI releases ([53a7325](https://github.com/mr-jones123/raga/commit/53a73254eeceba1298c98823c275fff8331bb0b8))
+* store instance memory in SQLite with selectable memory backends ([6c4997b](https://github.com/mr-jones123/raga/commit/6c4997be478c430c27ad378fa4d87bafc12f2444))
+* **tui:** add /diff dashboard for categorized git review ([03cb062](https://github.com/mr-jones123/raga/commit/03cb062df23b6591d33902f7d1bb815976dc4049))
+
+### Bug Fixes
+
+* publish CLI updates to npm through trusted publishing ([f236785](https://github.com/mr-jones123/raga/commit/f2367854e11a26576324116194ec299403cc2e6a))
+* **schemas:** regenerate keybindings schema for /diff bindings ([6ce96c7](https://github.com/mr-jones123/raga/commit/6ce96c73b6a742857be37e4bb79a83edb566106e))
+
+# Changelog
+
+Generated by scripts/raga-release.mjs from conventional commits. Do not edit by hand.
+
+## [0.8.0] - 2026-10-27
+
+### Breaking Changes
+
+- ship raga as the raga-cli npm package with its own ~/.raga/agent directory. raga keeps its own settings in ~/.raga/agent and no longer reads ~/.pi/agent; run /login again and reinstall packages, or set RAGA_CODING_AGENT_DIR=~/.pi/agent. (c42e6f0)
+
+### Added
+
+- **tui**: add /idle to show the turning raga wheel fullscreen (5c80c25)
+
+### Fixed
+
+- **ai**: keep long cache retention off for OpenCode DeepSeek V4.1 Flash (b25f3f6)
+
+## [0.7.1] - 2026-10-27
+
+### Fixed
+
+- **rlm**: leave kernel memory unlimited on macOS (f8637df)
+
+## [0.7.0] - 2026-10-26
+
+### Breaking Changes
+
+- **skills**: make peak the only installed skill (59f2d79)
+
+## [0.6.1] - 2026-10-26
+
+### Fixed
+
+- **rlm**: harden the cell dashboard (d63483f)
+
+## [0.6.0] - 2026-10-26
+
+### Added
+
+- **rlm**: show a spinning dashboard for running cells (99eab93)
+
+## [0.5.0] - 2026-10-26
+
+### Added
+
+- **skills**: add peak-setup with an explicit role picker (28fb28a)
+
+## [0.4.0] - 2026-10-26
+
+### Added
+
+- **skills**: rename poteto-mode to peak and ship all playbooks (953563a)
+
+## [0.3.0] - 2026-10-26
+
+### Added
+
+- **skills**: ship pstack and no-mistakes to root sessions (5b2923b)
+
+## [0.2.0] - 2026-10-26
+
+### Added
+
+- **rlm**: make raga always run in RLM mode (8e841d4)
+
+## [0.1.3] - 2026-10-26
+
+### Changed
+
+- **startup**: add a bundled launcher and document both run paths (2d9ab9e)
+
+## [0.1.2] - 2026-10-26
+
+_No user-visible changes._
+
+## [0.1.1] - 2026-10-26
+
+### Fixed
+
+- **release**: let docs-only changes cut a patch release (b743e2e)
+
+## [0.1.0] - 2026-10-26
+
+### Added
+
+- **release**: generate raga changelog from conventional commits (51c9add)
+- **rlm**: add the Python kernel and the TypeScript Kernel host (8fc6bae)
+- **rlm**: add RLM mode with the python tool, sub-LLM calls, and context (9c35e9b)
+- **rlm**: add rlm_query child sessions and kernel snapshots across resume and fork (fded120)
+- **rlm**: limit and report kernel memory (d81278a)
+- **instances**: add versioned adaptive instance system (aa0e264)
+- **bench**: add reproducible DeepSWE comparison harness (0abdcbb)
+- **instances**: add optional user-owned proof verification (16141d8)
+- **raga**: add a dedicated CLI and interactive branding (06e2311)
+- **raga**: describe raga's capabilities on startup (09a53ad)
+- **version**: show raga's own version and release every change (b3b32f0)
+
+### Fixed
+
+- **rlm**: return the whole file from read() and guide chunked llm_batch work (2aa8be5)
+- **raga**: close audit gaps in the formal flow (d86975d)
+- **release**: ignore vendored packages in lockstep checks (640d878)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+<p align="center">
+  <img alt="The eight-handled wheel of Mahoraga" src="docs/images/mahoraga-wheel.png" width="560">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">raga</h1>
+
+<p align="center"><i>あらゆる事象への適応<br>Adaptation to every phenomenon.</i></p>
+
+In *Jujutsu Kaisen*, the wheel above Mahoraga turns each time it takes a hit, and after every turn the same attack works less well. Raga is a coding harness built on that idea. Give it a long task, such as a refactor, a model training run, or a port of a legacy codebase, and it keeps working until a goal or a metric is met. Each error and each finished feature should make the next run of the same task smoother, with fewer mistakes.
+
+Raga is a fork of [pi](https://github.com/badlogic/pi-mono). It adds a native [Recursive Language Model](https://arxiv.org/abs/2512.24601) runtime. The model works inside a persistent Python REPL, keeps large inputs and its history in variables instead of its context window, and calls sub-LLMs and recursive sub-agents from code.
+
+## Status
+
+The RLM runtime works end to end. The adaptive layer, which lets the harness rewrite its own prompts, memories, and skills, is the next step. [docs/PROGRESS.md](docs/PROGRESS.md) tracks every milestone with the evidence for it.
+
+| Part | State |
+|---|---|
+| Persistent Python kernel owned by each session | Done |
+| `--rlm` mode, with `python` as the only model tool | Done |
+| `llm_query` and `llm_batch` sub-LLM calls, counted in session cost | Done |
+| `context.task`, `context.inputs`, and `context.history()`, which includes compacted messages | Done |
+| `rlm_query` recursive sub-agents, with a depth limit and parallel runs | Done |
+| Kernel variables saved and restored across resume and fork | Done |
+| Kernel memory limit and memory reporting | Done |
+| Self-editing harness state (prompt notes, memories, skills) with rollback | Not started |
+| Goal and metric loop (`--goal`, `--gate`, `--metric`) | Not started |
+| Native engineering skills (pstack, no-mistakes) | Not started |
+
+The packages still use pi's names (`@earendil-works/pi-*`). The `raga` command keeps its own user directory, `~/.raga/agent`, for logins, settings, sessions, skills, extensions, and packages. Set `RAGA_CODING_AGENT_DIR` to move it. It does not read `~/.pi/agent` or the shared `~/.agents/skills` folder, so an existing pi setup does not carry over. The `pi` command still uses `~/.pi/agent`.
+
+## Run it
+
+Raga needs Node.js 22.19 or newer, `uv`, and an AI provider that pi supports. Install it from npm:
+
+```bash
+npm install -g raga-cli
+raga
+```
+
+### Update
+
+Exit raga, then run:
+
+```bash
+raga update
+raga --version
+```
+
+This installs the latest published `raga-cli` release without deleting your settings or sessions. Restart raga afterward. If an older version cannot update itself, run `npm install -g raga-cli@latest`. See [docs/UPDATING.md](docs/UPDATING.md) for other update targets, source checkouts, and troubleshooting.
+
+### Run from source
+
+To run from source instead:
+
+```bash
+git clone https://github.com/mr-jones123/raga.git
+cd raga
+npm ci --ignore-scripts
+npm run generate-models -w packages/ai
+npm run build
+./raga
+```
+
+`./raga` runs the bundled build. It reaches the first frame in roughly half a second.
+
+```bash
+./raga-test.sh
+```
+
+Every session loads one skill, `peak`. It indexes 62 engineering references under `skills/peak/references/`, including the pstack playbooks and the managed no-mistakes workflow. Run `/skill:peak` and let it pick the reference for the task.
+
+While Python cells run, a small dashboard shows each active cell with a spinning wheel and its own color.
+
+`./raga-test.sh` runs the TypeScript sources through the resolver, so edits apply without a build. Module loading costs about a second more, because Node strips and resolves the whole source graph on every start. Use it while changing the code, and `./raga` otherwise.
+
+On the first `--rlm` run, raga creates a Python 3.11 environment with `uv` at `~/.raga/agent/rlm/venv`. To use another interpreter, set `RAGA_PYTHON`.
+
+Without `--rlm`, raga behaves like pi, with `read`, `bash`, `edit`, and `write` as model tools.
+
+## Local models
+
+On macOS and Linux, `/local-models` searches Hugging Face, asks before downloading missing weights, and starts models locally. The first recommendation is the official LFM3-1.7B GGUF Q4_K_M build through llama.cpp. The same command detects MLX models automatically on Apple Silicon; no separate backend command is needed. See [docs/LOCAL-MODELS.md](docs/LOCAL-MODELS.md) for setup, cache behavior, and limits.
+
+## Review changes
+
+`/diff` opens a read-only Git review dashboard. Browse changes by category (tests, modules, GitHub workflows, documentation, dependencies, configuration), inspect staged or working-tree changes, or pick a commit from history. Open a file to scroll its diff, and toggle to its full contents without leaving raga. See [docs/DIFF.md](docs/DIFF.md) for controls.
+
+## What the model does in RLM mode
+
+The kernel already exists when the model's first turn starts. Each `python` call runs a cell, and variables stay defined for the whole session. The model sees at most `rlm.outputLimit` characters of each cell's output. The full output stays in `cells`.
+
+```python
+import collections
+
+text = await read("messages.txt")              # the whole file, kept in a variable
+lines = text.splitlines()
+chunks = [lines[i:i + 40] for i in range(0, len(lines), 40)]
+labels = await llm_batch(
+    ["Label each message, one label per line:\n" + "\n".join(c) for c in chunks]
+)
+counts = collections.Counter(l.strip() for answer in labels for l in answer.splitlines())
+print(counts.most_common(5))
+```
+
+| Name | Use |
+|---|---|
+| `read`, `bash`, `edit`, `write` | Files and the shell. |
+| `llm_query`, `llm_batch` | One sub-LLM call, or many in parallel. |
+| `rlm_query` | Run a child session with its own kernel and return its answer. |
+| `context` | The task, input files from `--rlm-input`, and the session history. |
+| `cells` | The full output of every finished cell. |
+
+[docs/RLM.md](docs/RLM.md) is the reference for the protocol, the Python API, the settings, and the memory limit.
+
+## Benchmarks
+
+`bench/rlm/` runs the same tasks with pi's tools and with raga's RLM mode on the same model. The table shows Claude Haiku 4.5, seed 1, and 3 runs per row.
+
+| Task | Harness | Success | Mean answer error | Cost per run |
+|---|---|---|---|---|
+| T1: count billing complaints among 800 messages (truth 181) | pi | 0/3 | 49.0 | $0.337 |
+| | raga | 0/3 | 5.7 | $0.225 |
+| T2: multi-file Python refactor | pi | 2/3 | | $0.122 |
+| | raga | 2/3 | | $0.085 |
+
+[docs/BENCHMARKS.md](docs/BENCHMARKS.md) has the full numbers, the first run before a fix, and what limits each result.
+
+## Docs
+
+| File | Contents |
+|---|---|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the pi base works and where raga's layers attach. |
+| [docs/RLM.md](docs/RLM.md) | The RLM runtime reference. |
+| [docs/PROGRESS.md](docs/PROGRESS.md) | Milestones, status, and decisions. |
+| [docs/BENCHMARKS.md](docs/BENCHMARKS.md) | Benchmark tasks and results. |
+| [docs/LOCAL-MODELS.md](docs/LOCAL-MODELS.md) | Search, download, and run local Hugging Face models with llama.cpp or MLX. |
+| [docs/UPDATING.md](docs/UPDATING.md) | Install and update the CLI, extensions, and model catalogs. |
+| [docs/RELEASING.md](docs/RELEASING.md) | Automatic npm publishing, versioning, and merging upstream pi. |
+| [packages/coding-agent/docs/](packages/coding-agent/docs/) | Pi's own docs, which still apply to everything raga inherits. |
+
+## Development
+
+```bash
+npm run check                                     # Lint, format, and type check
+./test.sh                                         # Tests without API keys
+uv run --no-project --with pytest --with dill \
+  pytest packages/coding-agent/python/tests -q     # Python kernel tests
+node scripts/raga-release.mjs version             # Version from raga release tags
+```
+
+Commit headers follow Conventional Commits. Semantic-release generates `CHANGELOG.md`, version tags, and GitHub Releases after CI passes on `main`. See [docs/RELEASING.md](docs/RELEASING.md). [AGENTS.md](AGENTS.md) has the rules for humans and agents.
+
+## Credits
+
+- [pi](https://github.com/badlogic/pi-mono) by Mario Zechner and contributors, the base of this repository (MIT).
+- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) by Prime Intellect, whose REPL design the kernel adapts (MIT).
+- [Recursive Language Models](https://arxiv.org/abs/2512.24601) by Alex L. Zhang, Tim Kraska, and Omar Khattab.
+- The wheel image is from *Jujutsu Kaisen* by Gege Akutami (Shueisha), taken from the [Jujutsu Kaisen Wiki](https://jujutsu-kaisen.fandom.com/wiki/Eight-Handled_Sword_Divergent_Sila_Divine_General_Mahoraga). It is used here as a fan reference and is not covered by this repository's license.
+
+## License
+
+MIT

package/bundled-skills/AGENTS.md

@@ -0,0 +1,5 @@
+# Default engineering workflows
+
+peak is the only skill. Read skills/peak/SKILL.md, then the reference it names from skills/peak/references/<name>/SKILL.md. Read skills/peak/references/raga-runtime/SKILL.md before following a portable workflow. Tool names in inherited prose refer to the native Python adapter, not external editor APIs. Use native children and isolated workspaces. All skill authoring is candidate-only. The supervisor owns evidence, promotion, credentials, publication, and backend lifecycle.
+
+No-mistakes is available but not enabled automatically. Its managed runtime requires explicit provisioning and repository enablement. A validation-step child cannot control an outer gate. Never interpret a skipped or overridden check as fully verified.

package/bundled-skills/README.md

@@ -0,0 +1,25 @@
+# Portable default skills
+
+New instances copy this pack into their first accepted revision. Each session reads its pinned copy. Updating package assets does not rewrite an existing instance.
+
+The pack installs three skills. raga-artifacts makes slides and documents with Pele diagrams and exports them as HTML and PDF. bend turns rules the user states into Bend laws and proofs and checks them with the bend CLI. peak is the engineering workflow. Its 62 references hold 55 portable pstack workflows, four companion workflows, the native create-skill and raga-runtime adapters, and the managed no-mistakes workflow. It excludes make-bot-ui and editor-only services. The original public no-mistakes text stays unchanged under skills/peak/references/no-mistakes/upstream.
+
+Read [peak](skills/peak/SKILL.md) to pick a reference. Read [the native runtime](skills/peak/references/raga-runtime/SKILL.md) for the Python API. Read [the workflow guide](docs/guide/README.md) for the reference map. In instance sessions, workers return supervisor-owned workspace changes rather than Git commits. Ordinary sessions keep code changes in the parent session and use read-only children. Skill changes go through candidate_read, candidate_write, and candidate_commit. Promotion remains a trusted operator operation.
+
+## Sources and regeneration
+
+bundle.json records source commits, source-file hashes, adapted-file hashes, licenses, and runtime dependencies. Regenerate from cursor/plugins at eb4db2b55b2b7dec3d9282754cddf0a56bf4ff10, no-mistakes at 4822244e763fd4c3d7f48be6433f92df10bb5b33, and the published commander 14.0.0 package tree. From the repository root, run node scripts/raga-sync-skills.mjs with those three source directories as positional arguments. The generator compares every imported asset with the checked-in source hashes and refuses missing, added, or modified source files. A deliberate upstream update must review the source hashes and license changes as well as the adaptation.
+
+Pstack's MIT notice is in [licenses/pstack](licenses/pstack). Companion notices are in [licenses/cursor-team-kit](licenses/cursor-team-kit). No-mistakes and Commander have their own [no-mistakes](licenses/no-mistakes) and [Commander](licenses/commander) notices.
+
+## Optional capabilities and authorization
+
+Run capability_report() in the native Python session to inspect Node, Git, terminal support, Java, GitHub, the local Playwright browser, Mermaid, and the pinned TLC jar. Missing optional tools report prerequisites without installing dependencies. Runtime versions and pinned assets are in dependencies.json.
+
+No-mistakes v1.84.0 requires separate operator approvals for provisioning, network-enabled repository enablement, validation, gate responses, and lifecycle changes. The model API permits inspect, status, and restricted run after explicit enablement. It cannot supply approval or respond to a gate. Push, PR, CI, and automatic yes mode require separate operator grants. A stopped daemon requires explicit start before another run.
+
+The backend keeps HOME and NM_HOME below instance state, disables telemetry and update checks, and avoids OS service installation. It does not copy credentials or inherit ambient credentials. A runnable pipeline adapter must receive credentials through an explicitly approved wrapper or explicit trusted environment values. Version, JSON events, and durable sessions are probed before enablement.
+
+## Integration checks
+
+From packages/coding-agent, run the focused Vitest files test/instances-bundle.test.ts and test/instances-no-mistakes.test.ts after integration. The separate test/instances-no-mistakes-smoke.test.ts is opt-in with RAGA_NM_SMOKE=1, RAGA_NM_AGENT_EXECUTABLE, and RAGA_NM_AGENT_VERSION. Its optional JSON RAGA_NM_AGENT_ARGS and RAGA_NM_AGENT_ENV are explicit adapter inputs. The smoke creates a disposable Git remote, uses the actual pinned backend, and asserts that the feature branch is not published. It can use network and paid model calls. Do not enable it without authorization.

package/bundled-skills/agents/comment-sicko.json

@@ -0,0 +1,9 @@
+{
+  "name": "comment-sicko",
+  "instructions": "agents/comment-sicko.md",
+  "modelRole": "judgment",
+  "skills": [
+    "raga-runtime",
+    "peak"
+  ]
+}

package/bundled-skills/agents/comment-sicko.md

@@ -0,0 +1,28 @@
+
+# Comment Sicko
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/bundled-skills/agents/model-roles.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "code": null,
+  "judgment": null,
+  "verification": null,
+  "rules": "Null inherits the current model. Set real provider/model selectors in a candidate revision. Same-family seats are not model diversity.",
+  "feature, refactoring": null,
+  "bug-fix": null,
+  "perf-issue": null,
+  "hillclimb": null,
+  "hardest tasks": null,
+  "judgment and prose": null,
+  "how explorer": null,
+  "how explainer": null,
+  "why investigator": null,
+  "why synthesizer": null,
+  "teach explainer": null,
+  "swarm workers": null,
+  "arena cross-judge": null,
+  "reflect synthesizer": null,
+  "architect runners": [
+    null,
+    null
+  ],
+  "arena runners": [
+    null,
+    null
+  ],
+  "arena cross-judge pool": [
+    null,
+    null
+  ],
+  "interrogate reviewers": [
+    null,
+    null
+  ],
+  "reflect reviewers": [
+    null,
+    null
+  ]
+}

package/bundled-skills/agents/poteto-agent.json

@@ -0,0 +1,9 @@
+{
+  "name": "poteto-agent",
+  "instructions": "agents/poteto-agent.md",
+  "modelRole": "code",
+  "skills": [
+    "raga-runtime",
+    "peak"
+  ]
+}

package/bundled-skills/agents/poteto-agent.md

@@ -0,0 +1,4 @@
+
+# Poteto subagent
+
+You are operating as peak's full agent style. The chat that receives `/peak` owns the playbook, the todo list, and every native child call. You are one of its delegates. Read the `peak` skill's `SKILL.md` in full before doing any work, including its inline Principles index. The native helper supplies the pinned resource root and the complete required skill bodies. Resolve every additional leaf from that root. Never search a global plugin installation. Navigate to a leaf `principle-*` skill whenever you apply that principle.

package/bundled-skills/agents/worker.json

@@ -0,0 +1,8 @@
+{
+  "name": "worker",
+  "instructions": "agents/worker.md",
+  "modelRole": "code",
+  "skills": [
+    "raga-runtime"
+  ]
+}

package/bundled-skills/agents/worker.md

@@ -0,0 +1 @@
+Read the pinned native runtime adapter. Follow the assignment and its permissions. Preserve unrelated changes. Return concrete evidence, assumptions, and unresolved blockers. Do not promote revisions, publish, or control an outer no-mistakes gate.