rubik 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/ATTRIBUTION.md +4 -0
- data/CHANGELOG.md +115 -0
- data/README.md +137 -268
- data/bin/rubik +9 -0
- data/lib/rubik/cli/workspace_trust.rb +78 -0
- data/lib/rubik/kernel/init.rb +15 -0
- data/lib/rubik/lsp/client.rb +3 -2
- data/lib/rubik/orchestrator/auto_apply.rb +1 -1
- data/lib/rubik/orchestrator/subagent/activation.rb +29 -4
- data/lib/rubik/orchestrator/subagent/builtin_types.rb +117 -0
- data/lib/rubik/orchestrator/subagent/dynamic_store.rb +119 -0
- data/lib/rubik/orchestrator/subagent/instance.rb +8 -36
- data/lib/rubik/orchestrator/subagent/journal.rb +77 -4
- data/lib/rubik/orchestrator/subagent/profile_contract.rb +187 -0
- data/lib/rubik/orchestrator/subagent/profile_snapshot.rb +72 -0
- data/lib/rubik/orchestrator/subagent/reuse.rb +2 -1
- data/lib/rubik/orchestrator/subagent/scoped_registry.rb +2 -0
- data/lib/rubik/orchestrator/subagent/spawn_transaction.rb +170 -0
- data/lib/rubik/orchestrator/subagent/start_gate.rb +98 -0
- data/lib/rubik/orchestrator/subagent/supervisor.rb +4 -67
- data/lib/rubik/orchestrator/subagent/type_definition.rb +84 -0
- data/lib/rubik/orchestrator/subagent/type_registry.rb +139 -159
- data/lib/rubik/orchestrator/turn_executor/subagent_channel.rb +4 -2
- data/lib/rubik/platform/process.rb +78 -1
- data/lib/rubik/prompt/context_builder.rb +54 -20
- data/lib/rubik/prompt/doctrine.rb +158 -22
- data/lib/rubik/prompt/token_estimator.rb +5 -3
- data/lib/rubik/prompt/tool_teachings.rb +19 -12
- data/lib/rubik/sandbox/driver/bubblewrap.rb +13 -59
- data/lib/rubik/sandbox/driver/docker.rb +14 -60
- data/lib/rubik/sandbox/driver/podman.rb +13 -56
- data/lib/rubik/sandbox/driver/process.rb +12 -64
- data/lib/rubik/security/guard.rb +1 -1
- data/lib/rubik/storage/store.rb +52 -11
- data/lib/rubik/tools/builtins/define_subagent.rb +69 -0
- data/lib/rubik/tools/builtins/storage.rb +8 -5
- data/lib/rubik/tools/builtins/subagent.rb +20 -53
- data/lib/rubik/tools/builtins/synthesis.rb +6 -1
- data/lib/rubik/tools/builtins.rb +1 -0
- data/lib/rubik/tools/diagnostic_reporter.rb +2 -1
- data/lib/rubik/tools/fuzzy_matcher.rb +39 -19
- data/lib/rubik/tools/truncator.rb +54 -21
- data/lib/rubik/version.rb +1 -1
- metadata +10 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b71f1262ecc5dbd53e712da9df276b2fd744a1c797a05917ad4c103ead720b4c
|
|
4
|
+
data.tar.gz: 9c7d57397bfb5a8dfa4b34846bd51ec7ade3fcade0462cbf7f03d9d00ecb576c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5994b70d91d9673cb1ea08f1eb39f9f04aa446ea9edcb61bc558d1b81f79825e205a12690dec3b652901d3176061b74012f48bd7a34d6f1b49c6d181219ada33
|
|
7
|
+
data.tar.gz: 79037bc56238a6eca4f6017e0d23c9b79af836fa5593281cb9005c31750a4f08513d0c78c8ca97c3f83b6cb41643757852a4021778b6c6e2da7a9187e9ea2120
|
data/ATTRIBUTION.md
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -10,6 +10,121 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
|
10
10
|
|
|
11
11
|
Nothing yet.
|
|
12
12
|
|
|
13
|
+
## [0.3.1] - 2026-10-19
|
|
14
|
+
|
|
15
|
+
A hygiene patch: the Truncator honors the budgets you give it across
|
|
16
|
+
threads and separators, and the fuzzy matcher's Levenshtein fallback
|
|
17
|
+
gets much cheaper and UTF-8 safe.
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
|
|
21
|
+
- **Truncator honors caller budgets (#189):** the `:head_tail`
|
|
22
|
+
strategy drops its hardcoded `clamp(1, 150)` / `clamp(1, 6000)`
|
|
23
|
+
caps — `max_lines` and `max_chars` are honored as given, small
|
|
24
|
+
budgets (`max_lines <= 1`) stay under their ceilings, and inputs
|
|
25
|
+
shorter than the budget no longer duplicate or overlap lines;
|
|
26
|
+
non-default separators no longer bypass the budget check (small
|
|
27
|
+
texts were wrongly reported `truncated: true`); omitted-line
|
|
28
|
+
accounting matches byte-budget slicing; and negative budgets clamp
|
|
29
|
+
to zero.
|
|
30
|
+
- **Truncator line separation is thread-safe (#187):** `truncate`
|
|
31
|
+
takes an explicit `separator: "\n"` instead of reading the ambient
|
|
32
|
+
`$/` global, removing cross-thread separator races and the Ruby
|
|
33
|
+
3.4+ deprecation warnings.
|
|
34
|
+
- **FuzzyMatcher survives invalid UTF-8 (#185):** the Levenshtein
|
|
35
|
+
fallback scrubs invalid byte sequences before codepoint iteration
|
|
36
|
+
instead of raising.
|
|
37
|
+
|
|
38
|
+
### Changed
|
|
39
|
+
|
|
40
|
+
- **Levenshtein fallback is ~31% faster with 96% fewer allocations
|
|
41
|
+
(#185):** codepoint iteration with a single mutation buffer
|
|
42
|
+
replaces per-character string and row-array churn.
|
|
43
|
+
- **LSP reader-thread failures are structured (#184):** JSON parse
|
|
44
|
+
errors and reader exceptions log through `Rubik::Log.warn(:lsp, …)`
|
|
45
|
+
instead of bare `Kernel#warn`.
|
|
46
|
+
|
|
47
|
+
## [0.3.0] - 2026-10-18
|
|
48
|
+
|
|
49
|
+
The subagent-governance minor: runtime-defined archetypes become
|
|
50
|
+
context-scoped and reversible, spawn turns transactional, outcomes
|
|
51
|
+
are measured, and the first interactive launch asks before trusting
|
|
52
|
+
a workspace. Prompt teachings and tool schemas are aligned against
|
|
53
|
+
the declared contracts.
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
|
|
57
|
+
- **Context-scoped, reversible archetype registration (#175, closes
|
|
58
|
+
#171):** runtime `define_subagent` profiles are owned by an explicit
|
|
59
|
+
runtime context with LIFO revision stacks and context-bound disposal
|
|
60
|
+
inverses — disposing the owner pops the registration and restores
|
|
61
|
+
the prior profile; stale out-of-order cleanups remove only what they
|
|
62
|
+
own; built-ins stay reserved; re-registering a live archetype
|
|
63
|
+
requires `replace: true`; and nested profiles are owned and cleaned
|
|
64
|
+
up by the child context.
|
|
65
|
+
- **Workspace trust prompt (#183, closes #182):** interactive launches
|
|
66
|
+
in an untrusted workspace show the resolved path, explain Rubik's
|
|
67
|
+
file and command capabilities and the `buffer.model_can_apply:
|
|
68
|
+
false` limitation, and offer a per-workspace Trust and continue or
|
|
69
|
+
Exit choice (exit is the default); script and non-interactive
|
|
70
|
+
launches do not block on the prompt.
|
|
71
|
+
- **Validated subagent profile contracts (#177, closes #172):** custom
|
|
72
|
+
archetypes declare required coeffects and allowlisted capability
|
|
73
|
+
grants; profiles default to no write or nested-spawn grants; invalid
|
|
74
|
+
names, dependencies, grants and field limits return structured
|
|
75
|
+
validation errors before registration; custom tool filters derive
|
|
76
|
+
only from allowlisted grants.
|
|
77
|
+
- **Subagent profile outcomes and bounded prompt visibility (#179,
|
|
78
|
+
closes #174):** root prompts keep every built-in and show only the
|
|
79
|
+
eight newest active custom profiles; run journals record profile
|
|
80
|
+
identity and version, outcome, bounded redacted error summaries,
|
|
81
|
+
duration, step and tool-call counts, and provider-reported token
|
|
82
|
+
usage — missing token and cost data are marked unavailable, never
|
|
83
|
+
estimated.
|
|
84
|
+
|
|
85
|
+
### Fixed
|
|
86
|
+
|
|
87
|
+
- **Subagent spawn is transactional (#178, closes #173):** required
|
|
88
|
+
coeffects are validated before the worker starts; a startup failure
|
|
89
|
+
rolls back the child context, scoped registry, kernel registration,
|
|
90
|
+
instance and generated ID; each instance pins an immutable profile
|
|
91
|
+
snapshot (redeploys keep the original); and honest spawn failures
|
|
92
|
+
reach the maestro.
|
|
93
|
+
- **The system prompt follows active tools and mode (#170, closes
|
|
94
|
+
#166):** teachings for gated tools are filtered when their
|
|
95
|
+
coeffects are unsatisfied, plan-only mode directs no tool calls or
|
|
96
|
+
synthesis, and read-only orientation vs delegated execution is
|
|
97
|
+
harmonized across rules and role headers.
|
|
98
|
+
- **Storage and Vakanüvis write rules are aligned (#169, closes
|
|
99
|
+
#165):** direct `storage put` targets work artifacts
|
|
100
|
+
(goal/plan/review/note) while durable `memory` cards and `wiki`
|
|
101
|
+
pages route through `vakanuvis` record/digest when available; the
|
|
102
|
+
tool declaration documents the contract and the coder prompt
|
|
103
|
+
surfaces durable lessons to the maestro.
|
|
104
|
+
- **Tool teachings match declared schemas (#168, closes #167):**
|
|
105
|
+
`replace_file_content` guidance drops the unadvertised aliases
|
|
106
|
+
(runtime tolerance preserved) and `synthesize_tool` requires
|
|
107
|
+
`params_schema` when the synthesized tool accepts arguments.
|
|
108
|
+
|
|
109
|
+
### Changed
|
|
110
|
+
|
|
111
|
+
- **Documentation navigation:** user and developer guides reorganized
|
|
112
|
+
under `docs/`, README quickstart and feature summary refreshed, and
|
|
113
|
+
GitHub issue and pull request templates plus a code of conduct
|
|
114
|
+
added; provider and local model IDs refreshed across README,
|
|
115
|
+
configuration, command, API and first-session examples.
|
|
116
|
+
- **Process stream capture is consolidated (#180):**
|
|
117
|
+
`Rubik::Platform.popen_capture` centralizes Open3 startup,
|
|
118
|
+
concurrent stdout/stderr capture, exit-status mapping and timeout
|
|
119
|
+
process-tree termination; ProcessDriver, Bubblewrap, Docker and
|
|
120
|
+
Podman drivers share it.
|
|
121
|
+
- **Hot paths get cheaper:** `TokenEstimator.estimate_text` switches
|
|
122
|
+
to exact integer math with zero allocations (~7.8% on history
|
|
123
|
+
estimation, #181); `Store#search_ranked` ranking cuts allocations
|
|
124
|
+
by ~43% (#176).
|
|
125
|
+
- **Deps:** `tree_sitter_language_pack` bumps to 1.22.1 (#162); dev
|
|
126
|
+
rubocop to 1.92.0 (#163).
|
|
127
|
+
|
|
13
128
|
## [0.2.0] - 2026-10-16
|
|
14
129
|
|
|
15
130
|
The first minor of the 0.2 era is a hardening minor: a reproducible
|
data/README.md
CHANGED
|
@@ -1,297 +1,166 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Rubik
|
|
2
2
|
|
|
3
3
|
English | [Türkçe](README.tr.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
6
|
+
[](https://rubygems.org/gems/rubik)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://www.ruby-lang.org/)
|
|
9
|
+
[](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
10
|
+
[](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
[](https://rubygems.org/gems/rubik)
|
|
9
|
-
[](https://www.ruby-lang.org)
|
|
10
|
-
[](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
11
|
-
[](AGENTS.md)
|
|
12
|
-
[](COMMANDS.md)
|
|
13
|
-
[](CONFIG.md)
|
|
14
|
-
[](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
15
|
-
[](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
12
|
+
## About
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
Rubik is a Ruby terminal coding agent and interactive REPL. It connects an LLM to
|
|
15
|
+
workspace tools for reading and changing code, while staging file edits in a
|
|
16
|
+
reviewable in-memory buffer. Developers can use it as a CLI or embed its runtime
|
|
17
|
+
from Ruby with `require "rubik"`.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Rubik is for developers who want an agent in their terminal and control over how
|
|
20
|
+
its changes reach disk. It supports OpenAI-compatible providers, Anthropic, and
|
|
21
|
+
local Ollama. Its security checks and optional OS sandbox are described in
|
|
22
|
+
[Security](SECURITY.md).
|
|
20
23
|
|
|
21
|
-
|
|
24
|
+
## Quickstart
|
|
22
25
|
|
|
23
|
-
|
|
26
|
+
**Prerequisites:** Ruby 3.4 or later and an OpenRouter API key for this example.
|
|
27
|
+
The gem is the shortest install path:
|
|
24
28
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
### From the gem
|
|
28
|
-
|
|
29
|
-
Requires **Ruby 3.4+**:
|
|
30
|
-
|
|
31
|
-
CI tests Linux on Ruby 3.4 (minimum) and 4.0, and macOS and Windows on
|
|
32
|
-
Ruby 4.0. Each job installs dependencies, runs the full unit/integration suite,
|
|
33
|
-
and builds, installs and smokes the gem (`rubik --version` and `require "rubik"`).
|
|
34
|
-
See [CI runs](https://github.com/ozgurulukir/rubik/actions/workflows/ci.yml)
|
|
35
|
-
for results on a specific commit; platform artifacts contain environment details,
|
|
36
|
-
installation/smoke logs, test counts and skip reasons. Other Ruby/OS combinations
|
|
37
|
-
are not covered by this bounded matrix.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
```bash
|
|
29
|
+
```sh
|
|
41
30
|
gem install rubik
|
|
42
31
|
```
|
|
43
32
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
rubik
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
or with Bundler:
|
|
51
|
-
|
|
52
|
-
```ruby
|
|
53
|
-
gem "rubik"
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
#### Platform notes
|
|
57
|
-
|
|
58
|
-
| Platform | Install experience |
|
|
59
|
-
| :--- | :--- |
|
|
60
|
-
| 🐧 Linux / 🍎 macOS | `gem install rubik` — dependencies ship prebuilt. |
|
|
61
|
-
| 🪟 Windows | `tree_sitter_language_pack` has no Windows prebuilt and compiles from source: install Rust with the GNU toolchain and export `RUST_TARGET=x86_64-pc-windows-gnu` before installing. The exact, working recipe is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). |
|
|
62
|
-
|
|
63
|
-
### From source
|
|
64
|
-
|
|
65
|
-
**Prerequisites**
|
|
66
|
-
|
|
67
|
-
- **Ruby:** 3.4.0 or later (`ruby -v`)
|
|
68
|
-
- **Linux / macOS:** Via the system package manager, `rbenv`, `rvm`, or `asdf`.
|
|
69
|
-
- **Windows:** [Scoop](https://scoop.sh) (`scoop install ruby`) or [RubyInstaller with DevKit](https://rubyinstaller.org).
|
|
70
|
-
- **Git:** Git 2.30+ (`git -v`)
|
|
71
|
-
- **LLM Provider:** Local [Ollama](https://ollama.ai) (`ollama run qwen2.5-coder:7b`) or a DeepSeek, OpenRouter, Anthropic, or OpenAI API key.
|
|
72
|
-
|
|
73
|
-
Clone the project, install the dependencies, and start the REPL:
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
git clone https://github.com/ozgurulukir/rubik.git
|
|
77
|
-
cd rubik
|
|
78
|
-
bundle install
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
#### 🐧 Linux & 🍎 macOS (POSIX)
|
|
33
|
+
Set the key in your shell, then start Rubik. Replace the example value with your
|
|
34
|
+
key:
|
|
82
35
|
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
./bin/rubik
|
|
86
|
-
|
|
87
|
-
# Veya sistemde global kullanmak için ~/.local/bin dizinine bağlayın:
|
|
88
|
-
ln -sf $(pwd)/bin/rubik ~/.local/bin/rubik
|
|
36
|
+
```sh
|
|
37
|
+
export OPENROUTER_API_KEY="your-key"
|
|
89
38
|
rubik
|
|
90
39
|
```
|
|
91
40
|
|
|
92
|
-
|
|
93
|
-
> **The gem and a clone can coexist.** On POSIX the symlink always runs your clone: `bin/rubik` resolves `lib/` from its own real path, so a `git pull` is live on the very next launch — even while the `rubik` gem stays installed. The gem-installed `rubik` keeps serving the last released version until you run `gem update rubik`. On Windows, whichever `bin` folder comes first in `PATH` wins — `where.exe rubik` shows the winner.
|
|
94
|
-
|
|
95
|
-
#### 🪟 Windows (PowerShell / Command Prompt)
|
|
96
|
-
|
|
97
|
-
Rubik ships with built-in `.cmd`, `.bat`, and `.ps1` wrappers for Windows:
|
|
41
|
+
In PowerShell:
|
|
98
42
|
|
|
99
43
|
```powershell
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
# veya Command Prompt / Terminal üzerinden
|
|
104
|
-
.\bin\rubik.cmd
|
|
105
|
-
|
|
106
|
-
# veya Ruby üzerinden doğrudan
|
|
107
|
-
ruby bin\rubik
|
|
44
|
+
$env:OPENROUTER_API_KEY = "your-key"
|
|
45
|
+
rubik
|
|
108
46
|
```
|
|
109
47
|
|
|
110
|
-
|
|
111
|
-
> **The Global `rubik` Command on Windows:**
|
|
112
|
-
> By adding Rubik's `bin` folder to your environment variables (User PATH), you can launch it from any terminal simply by typing `rubik`:
|
|
113
|
-
> ```powershell
|
|
114
|
-
> [Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$PWD\bin", "User")
|
|
115
|
-
> ```
|
|
48
|
+
At the REPL prompt, register the provider and choose a model:
|
|
116
49
|
|
|
117
|
-
|
|
50
|
+
<!-- markdownlint-disable MD013 -->
|
|
118
51
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
# REPL içerisinden sağlayıcı ekleme:
|
|
123
|
-
rubik > !provider add deepseek openai_compatible https://api.deepseek.com/v1/chat/completions --key=sk-... --model=deepseek-coder --context=64000
|
|
124
|
-
rubik > !model deepseek/deepseek-coder
|
|
52
|
+
```text
|
|
53
|
+
!provider add openrouter openai_compatible https://openrouter.ai/api/v1/chat/completions --key-env=OPENROUTER_API_KEY --model=anthropic/claude-sonnet-5.5 --context=200000 -g
|
|
54
|
+
!model openrouter/anthropic/claude-sonnet-5.5
|
|
125
55
|
```
|
|
126
56
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
```bash
|
|
130
|
-
rubik > !model anthropic/claude-sonnet-5-5
|
|
131
|
-
```
|
|
57
|
+
<!-- markdownlint-enable MD013 -->
|
|
132
58
|
|
|
133
|
-
|
|
59
|
+
Then enter a prompt at the REPL:
|
|
134
60
|
|
|
135
61
|
```text
|
|
136
|
-
|
|
137
|
-
│ 🎲 Rubik v0.1.0 │
|
|
138
|
-
│ deepseek/deepseek-coder │
|
|
139
|
-
│ my_project · main │
|
|
140
|
-
│ !help komutlar · ctrl+c kes · !config ayarlar │
|
|
141
|
-
╰──────────────────────────────────────────────────────────╯
|
|
142
|
-
deepseek/deepseek-coder · ctx 3% · temiz · sandbox kapalı
|
|
143
|
-
rubik (my_project) [main] > !status
|
|
144
|
-
Project: my_project (main)
|
|
145
|
-
Default Model: deepseek/deepseek-coder
|
|
146
|
-
Dirty buffer: false
|
|
147
|
-
|
|
148
|
-
rubik (my_project) [main] > Kullanıcı kayıt formunu doğrulayan bir helper fonksiyonu yaz
|
|
149
|
-
✻ Düşünüyor… · 1s (ctrl+c: kes)
|
|
150
|
-
⏺ write_file — lib/validator.rb
|
|
151
|
-
⎿ 3 lines · 18ms
|
|
152
|
-
|
|
153
|
-
[Rubik] In-memory buffer updated. Type `!diff` to view, `!apply` to save.
|
|
154
|
-
|
|
155
|
-
rubik (my_project) [main] [DIRTY: 1 ✎] > !diff
|
|
156
|
-
+ def validate_user(params)
|
|
157
|
-
+ raise "Invalid email" unless params[:email]&.include?("@")
|
|
158
|
-
+ end
|
|
159
|
-
|
|
160
|
-
rubik (my_project) [main] [DIRTY: 1 ✎] > !test
|
|
161
|
-
Applied 1 file(s) before test. All 12 tests passed!
|
|
62
|
+
Summarize the files in this project.
|
|
162
63
|
```
|
|
163
64
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
>
|
|
170
|
-
>
|
|
171
|
-
>
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
Every guide ships as a bilingual pair — `X.md` (English, authoritative) alongside `X.tr.md` (Turkish translation).
|
|
267
|
-
|
|
268
|
-
### Architecture & Internals
|
|
269
|
-
|
|
270
|
-
| Guide | What it covers |
|
|
271
|
-
| :--- | :--- |
|
|
272
|
-
| 🌌 [AGENTS.md](AGENTS.md) | The Spatiotemporal Composability Protocol — theory, invariants, the fiber lifecycle state machine. |
|
|
273
|
-
| 🏗️ [ARCHITECTURE.md](ARCHITECTURE.md) | The 30 core domains and the responsibility matrix. |
|
|
274
|
-
| 🧬 [SELF_EVOLUTION.md](SELF_EVOLUTION.md) | How the LLM synthesizes tools, repairs services, and evolves its own runtime. |
|
|
275
|
-
| 🔌 [API.md](API.md) | Embedding the runtime from Ruby: config, tool registry, provider contract, orchestrator loop, error contracts. |
|
|
276
|
-
|
|
277
|
-
### User & Operator Guides
|
|
278
|
-
|
|
279
|
-
| Guide | What it covers |
|
|
280
|
-
| :--- | :--- |
|
|
281
|
-
| 🕹️ [COMMANDS.md](COMMANDS.md) | All 30+ REPL bang commands with parameters and usage scenarios. |
|
|
282
|
-
| 🧰 [TOOLS.md](TOOLS.md) | Catalog of the 34 built-in agent tools: parameters, risk classes, diagnostics. |
|
|
283
|
-
| ⚙️ [CONFIG.md](CONFIG.md) | Every configuration knob (models, LSP, buffer policy, sandbox, subagents, pruner…). |
|
|
284
|
-
| 🌍 [ENV.md](ENV.md) | Environment variables — single consolidated reference table. |
|
|
285
|
-
| 🖥️ [LSP.md](LSP.md) | Step-by-step language-server setup and diagnostics walkthrough. |
|
|
286
|
-
| 🔌 [PLUGINS.md](PLUGINS.md) | The drop-in plugin system: layout, manifests, zero-downtime reloads. |
|
|
287
|
-
|
|
288
|
-
### Project & Policy
|
|
289
|
-
|
|
290
|
-
| Guide | What it covers |
|
|
291
|
-
| :--- | :--- |
|
|
292
|
-
| 🤝 [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, test commands, commit/PR conventions, security reporting. |
|
|
293
|
-
| 🧪 [TESTING.md](TESTING.md) | Running the suite, naming conventions, test templates, flaky-test policy. |
|
|
294
|
-
| 🔒 [SECURITY.md](SECURITY.md) | Command gate, critical-write protection, synthesis gates, sandbox, audit log. |
|
|
295
|
-
| 📜 [ATTRIBUTION.md](ATTRIBUTION.md) | Open-source attributions and third-party notices. |
|
|
296
|
-
| 📜 [CHANGELOG.md](CHANGELOG.md) | Thematic release history; the full record lives in `git log`. |
|
|
297
|
-
| 📄 [LICENSE](LICENSE) | Software license (MIT). |
|
|
65
|
+
Use `!diff` to review staged file changes and `!apply` to write them to disk. See the
|
|
66
|
+
[first-session tutorial](docs/tutorials/first-session.md) for platform-specific
|
|
67
|
+
credential setup and a longer walkthrough. Windows gem installation may compile
|
|
68
|
+
a dependency from source; see the [installation guide](docs/how-to/installation.md).
|
|
69
|
+
|
|
70
|
+
> **Safety note:** Model-generated code and commands can be incorrect or unsafe. Review
|
|
71
|
+
> changes with `!diff` and run tests before relying on them. For strict human approval
|
|
72
|
+
> of **buffered file changes only**, set `buffer.auto_apply: manual` and
|
|
73
|
+
> `buffer.model_can_apply: false`. These settings do not gate shell commands or
|
|
74
|
+
> background processes: the command safety gate checks them, but allowed commands run
|
|
75
|
+
> without a separate per-command approval prompt. The OS sandbox is disabled by default;
|
|
76
|
+
> run untrusted code in an isolated environment. See [Security](SECURITY.md).
|
|
77
|
+
|
|
78
|
+
## Features
|
|
79
|
+
|
|
80
|
+
1. **Core · Cross-platform CLI.** Run the terminal agent and REPL on Linux,
|
|
81
|
+
macOS, or Windows. The CI matrix covers Ubuntu with Ruby 3.4 and 4.0, and
|
|
82
|
+
macOS and Windows with Ruby 4.0. In the Windows CI environment, gem
|
|
83
|
+
installation compiles a native dependency with the Rust GNU toolchain. See
|
|
84
|
+
the [installation guide](docs/how-to/installation.md).
|
|
85
|
+
2. **Core · Staged file edits.** Model writes go to an in-memory virtual buffer;
|
|
86
|
+
inspect them with `!diff`, apply them with `!apply`, or discard unapplied
|
|
87
|
+
edits with `!undo`.
|
|
88
|
+
3. **Core · Review control and write semantics.** To require operator approval
|
|
89
|
+
for buffered file changes, set `buffer.model_can_apply: false` together with
|
|
90
|
+
`buffer.auto_apply: manual`. This does not add approval prompts for shell
|
|
91
|
+
commands or background processes; see [security practices](SECURITY.md). Each
|
|
92
|
+
file is written atomically, but a multi-file apply is not a transaction: a
|
|
93
|
+
partial failure leaves the remaining changes dirty and reports applied,
|
|
94
|
+
failed, and pending files. See [buffer configuration](docs/how-to/configuration.md).
|
|
95
|
+
4. **Core · Multiple workspace roots.** Add sibling or external directories as
|
|
96
|
+
read-only roots by default, or allow writes with `--rw`; additional roots can
|
|
97
|
+
join code search and the AST index. See the [`!workspace` commands](docs/reference/commands.md).
|
|
98
|
+
5. **Core · Guarded command execution.** Commands pass through Rubik's safety
|
|
99
|
+
checks. Bubblewrap, Docker, or Podman isolation is optional and disabled by
|
|
100
|
+
default. See [security practices](SECURITY.md).
|
|
101
|
+
6. **Models · Provider and role routing.** Connect OpenAI-compatible endpoints,
|
|
102
|
+
Anthropic, OpenAI, or local Ollama, then assign models to default, fast, and
|
|
103
|
+
advanced roles or use task-based routing. See [provider configuration](docs/how-to/configuration.md).
|
|
104
|
+
7. **Code intelligence · Hybrid AST.** Prism parses Ruby; Tree-Sitter grammars
|
|
105
|
+
cover Python, Go, Rust, TypeScript, TSX, JavaScript, C, C++, and Zig. Symbol
|
|
106
|
+
and call-graph indexing can warm in the background and persists to a local
|
|
107
|
+
cache. If Tree-Sitter is unavailable, Rubik can use regex extractors, which
|
|
108
|
+
have structural limits. Parsing errors have structured statuses, and a
|
|
109
|
+
failed re-index preserves previously indexed symbols. See [architecture](docs/explanation/architecture.md).
|
|
110
|
+
8. **Code intelligence · Live LSP diagnostics.** Configured language servers
|
|
111
|
+
can start on demand and return compiler or linter diagnostics after edits.
|
|
112
|
+
Missing or failing servers do not block a session; Rubik falls back to its
|
|
113
|
+
built-in syntax and AST analysis. See [language-server setup](docs/how-to/language-servers.md).
|
|
114
|
+
9. **Code intelligence · Native fast paths.** When available, ripgrep and Git
|
|
115
|
+
accelerate search and context scanning; Rubik falls back to pure Ruby when
|
|
116
|
+
those binaries are missing or native paths are disabled. Control them through
|
|
117
|
+
`tools.native` or `RUBIK_NATIVE`. See [configuration](docs/how-to/configuration.md).
|
|
118
|
+
10. **Extensions · Runtime synthesis.** The model can create REPL commands and
|
|
119
|
+
tools during a session. Managed runtime effects register cleanup actions
|
|
120
|
+
and unwind them in LIFO order. See [self-evolution](docs/explanation/self-evolution.md).
|
|
121
|
+
11. **Extensions · Plugins.** Load or reload drop-in Ruby plugins from user or
|
|
122
|
+
project directories. SHA-256 manifests detect modified files, but plugins
|
|
123
|
+
execute arbitrary Ruby in the host process and are not sandboxed. See the
|
|
124
|
+
[plugin guide](docs/how-to/plugins.md).
|
|
125
|
+
12. **Extensions · MCP servers.** Connect external stdio servers and expose
|
|
126
|
+
discovered tools through Rubik's registry. Lifecycle cleanup removes proxy
|
|
127
|
+
tools and attempts to stop child processes when the server is disconnected.
|
|
128
|
+
See [MCP commands](docs/reference/commands.md).
|
|
129
|
+
13. **Recovery · Live service repair.** Inspect runtime state, verify a
|
|
130
|
+
replacement command in a disposable context, then promote it without
|
|
131
|
+
restarting the process. Failed promotion or persistence unwinds session
|
|
132
|
+
changes; if a previous service cannot be restored, the repair result reports
|
|
133
|
+
incomplete rollback. Successful operator configuration saves remain in
|
|
134
|
+
place. See [runtime repair](docs/explanation/runtime-repair.md).
|
|
135
|
+
14. **Long sessions · Structured goal ledger.** The `!goal` loop keeps a
|
|
136
|
+
revision-guarded record of objectives, tasks, findings, and decisions;
|
|
137
|
+
current state survives compaction, and configured verification checks run
|
|
138
|
+
at step boundaries. See [goal commands](docs/reference/commands.md).
|
|
139
|
+
15. **Long sessions · Context pruning.** A pruner can propose what to keep,
|
|
140
|
+
drop, or summarize; the harness validates the plan and applies it at a turn
|
|
141
|
+
boundary. The operator can also invoke it with `!prune`. See [pruner settings](docs/how-to/configuration.md).
|
|
142
|
+
16. **Long sessions · Vakanüvis annals.** When configured, the chronicler
|
|
143
|
+
records session turns and subagent events; its distiller can build memory
|
|
144
|
+
notes and a wiki skeleton. See [runtime architecture](docs/explanation/architecture.md).
|
|
145
|
+
17. **Interaction · Live monitoring and TUI.** Choose quiet, normal, verbose,
|
|
146
|
+
or debug output. The interface combines a statusline, spinner, Markdown
|
|
147
|
+
renderer, colored diff view, and interactive `!agents` board. `NO_COLOR` and
|
|
148
|
+
pipe mode fall back to plain text, and session logs omit ANSI codes. See
|
|
149
|
+
[UI configuration](docs/how-to/configuration.md).
|
|
150
|
+
18. **Runtime · Cooperative I/O concurrency.** A pure-Ruby Fiber Scheduler can
|
|
151
|
+
overlap supported blocking I/O on one thread; it does not parallelize CPU
|
|
152
|
+
work; disable it with `RUBIK_FIBER_SCHEDULER=off`. The capacity harness
|
|
153
|
+
exercises lifecycle checks at 1,000 epochs, 100 and 1,000 concurrent loopback
|
|
154
|
+
requests, and AST-cache behavior. See [architecture](docs/explanation/architecture.md)
|
|
155
|
+
and [testing](docs/development/testing.md).
|
|
156
|
+
|
|
157
|
+
## Documentation
|
|
158
|
+
|
|
159
|
+
Browse the [documentation index](docs/index.md) for tutorials, how-to guides,
|
|
160
|
+
references, architecture explanations, and development guidance. The
|
|
161
|
+
[changelog](CHANGELOG.md) records releases.
|
|
162
|
+
|
|
163
|
+
## Contributing and policies
|
|
164
|
+
|
|
165
|
+
[Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) ·
|
|
166
|
+
[Security policy](SECURITY.md) · [License](LICENSE)
|