rubino-agent 0.3.0

data/README.md

@@ -0,0 +1,200 @@
+# rubino
+
+A coding & automation **agent** — small, self-contained, and built to run *where the work is*: directly on your machine or inside a VM. You drop it onto a box and it works there, reachable over a CLI and an HTTP API. It is not a heavy framework; it's a lightweight agent with persistent memory, sessions, and context compaction. Built on [ruby_llm](https://github.com/crmne/ruby_llm).
+
+## Why rubino
+
+- **Runs where the work is** — a single gem on the machine (or VM) that holds the code, not a remote service you pipe files to.
+- **Persistent memory** — a tiny SQLite "Zep"-style fact store that learns about you and the project across sessions.
+- **Context compaction** — automatic compression with session lineage when the conversation outgrows the window.
+- **CLI *and* HTTP API** — an interactive terminal session for humans, a bearer-protected JSON + SSE API for programs.
+- **Real tools, gated** — read/write/edit, shell, ruby, git/github, grep/glob, a structured test runner, vision, and more, behind an approval model with a non-bypassable hardline floor.
+- **Built on ruby_llm** — provider-agnostic: MiniMax, OpenAI, Anthropic, Gemini, or an OpenAI-compatible gateway.
+
+## Install
+
+One line, Linux and macOS (x86_64 / arm64). Installs a compatible Ruby, then the gem — all in user space, no sudo:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh | bash
+```
+
+On **Linux** the installer fetches a precompiled Ruby via [`rv`](https://github.com/spinel-coop/rv). On **macOS**, if [Homebrew](https://brew.sh) is present it asks whether to use Homebrew (`brew install ruby`) or `rv`; without Homebrew it uses `rv` directly. Skip the prompt with `RUBINO_INSTALL_METHOD=brew` or `=rv`.
+
+> **Review before you pipe.** Piping a script into your shell runs whatever it contains. Read it first:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh -o install.sh
+> less install.sh && bash install.sh
+> ```
+
+The installer is idempotent — safe to re-run — and prints the exact `PATH` line for the `rubino` executable plus the next step.
+
+**Manual install** (if you'd rather not pipe, or already manage Ruby yourself):
+
+```bash
+# With rv (https://rv.dev):
+curl -LsSf https://rv.dev/install | sh
+rv ruby install 3.3.3
+rv run --ruby 3.3.3 gem install rubino-agent
+
+# Or with any Ruby >= 3.1 already on your PATH:
+gem install rubino-agent
+```
+
+## Quick Start
+
+```bash
+rubino setup        # guided first-run: pick a provider, paste a key
+rubino chat         # start chatting; ask "what does this project do?"
+```
+
+`rubino setup` runs an interactive wizard that picks a provider/model and stores your API key — no hand-editing of YAML to get a first answer. If you skip the wizard, a bare `rubino chat` from a fresh home launches it for you before the first message.
+
+New here? Read **[docs/getting-started.md](docs/getting-started.md)** — install → setup → first working message.
+
+In development:
+
+```bash
+git clone https://github.com/Jhonnyr97/rubino-agent.git
+cd rubino-agent
+bundle install
+bundle exec rubino setup
+bundle exec rubino chat
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- SQLite3
+- An LLM provider API key (MiniMax, OpenAI, Anthropic, or Google) — or any OpenAI-compatible gateway.
+
+## Essential commands
+
+| Command | What it does |
+|---|---|
+| `rubino setup` | Guided first-run: provider/model/key, config + database |
+| `rubino chat` | Interactive session (bare `chat` auto-resumes your last session) |
+| `rubino chat --new` | Start a fresh session instead of resuming |
+| `rubino prompt "..."` | One-shot, non-interactive (alias for `chat -q`) |
+| `rubino server` | Start the JSON API + SSE server |
+| `rubino doctor` | Check config, credentials, and database health |
+| `rubino tools` | List tools and their enabled/disabled state |
+| `rubino memory list` | Inspect stored memories (uses the active backend) |
+| `rubino version` | Print the version |
+| `rubino update` | Update to the latest published version via RubyGems |
+
+`rubino update` runs `gem update rubino-agent` under the active interpreter (multi-Ruby safe); for a source/dev checkout it points you back at the installer instead. On interactive boot rubino shows a single dim line when a newer version is available (`▸ rubino vX.Y available — run \`rubino update\``). The check is cached and refreshed out-of-band (once / 24h, short timeout), so it never slows startup and is silent offline. Set `RUBINO_NO_UPDATE_CHECK=1` to disable it (it is also off when not a TTY or under `CI`). It prints nothing until the gem is actually published. See **[docs/commands.md](docs/commands.md)**.
+
+Inside a chat, type `/help` for the slash commands (`/status`, `/sessions`, `/memory`, `/agents`, `/skills`, `/mode`, `/commands`, `/new`, …). The full reference is **[docs/commands.md](docs/commands.md)**.
+
+## Configuration
+
+Configuration lives in `~/.rubino/config.yml` (created by `rubino setup`); secrets go in `~/.rubino/.env`. Both follow `RUBINO_HOME` if set. A representative slice (defaults shown):
+
+```yaml
+model:
+  default: "openai/gpt-4.1"   # the shipped default — see the note below
+  provider: "auto"            # auto | openai | anthropic | bedrock | gemini | minimax | gateway
+  temperature: 0.3
+
+agent:
+  max_turns: 90
+  max_tool_iterations: 8
+
+memory:
+  enabled: true
+  backend: "sqlite"           # tiny-Zep FTS5 + graph-lite recall (default)
+  auto_extract: true
+
+compression:
+  enabled: true
+  threshold: 0.50
+
+jobs:
+  mode: "inline"              # inline | manual | worker
+
+tools:
+  workspace_strict: true      # sandbox write/edit/delete to the workspace
+  git: true
+  shell: true                 # ON by default; every command is still approval-gated
+  ruby: true
+  web: false                  # gates BOTH webfetch and websearch
+  memory: true
+```
+
+> **Heads-up on the default model.** The shipped `model.default` is `openai/gpt-4.1`, which ruby_llm's registry resolves to **OpenRouter** — so a first run with no OpenAI/OpenRouter key fails fast with guidance instead of hanging. Run `rubino setup` (the wizard defaults to OpenAI gpt-4.1) or set your provider/key explicitly. See **[docs/models-and-keys.md](docs/models-and-keys.md)**.
+
+Full reference (every key, env vars, precedence): **[docs/configuration.md](docs/configuration.md)**.
+
+## Documentation
+
+- **[Getting started](docs/getting-started.md)** — install → setup → first message
+- **[Models & keys](docs/models-and-keys.md)** — which provider/model/key, per-provider setup blocks
+- **[Commands](docs/commands.md)** — CLI subcommands + slash-command reference
+- **[Configuration](docs/configuration.md)** — full config + env vars + precedence
+- **[Tools](docs/tools.md)** — the built-in tool set and approval behavior
+- **[Skills](docs/skills.md)** — reusable instruction packs, the 3-level disclosure, and `SKILL_LOADED` observability
+- **[Memory](docs/memory.md)** — the SQLite tiny-Zep backend
+- **[Security](docs/security.md)** — approval model, hardline floor, TLS
+- **[Troubleshooting](docs/troubleshooting.md)** — keyed on the exact error strings
+- **[HTTP API](docs/api/v1.md)** · **[Jobs & cron](docs/jobs.md)** · **[OAuth providers](docs/oauth-providers.md)** · **[Architecture](docs/architecture.md)**
+- **[Contributing](CONTRIBUTING.md)** · **[Changelog](CHANGELOG.md)**
+
+## Built-in tools
+
+The agent ships **33 built-in tools**: `read`, `summarize_file`, `write`, `edit`, `multi_edit`, `grep`, `glob`, `git`, `github`, `shell`, `shell_output`, `shell_tail`, `shell_input`, `shell_kill`, `ruby`, `run_tests`, `apply_patch`, `webfetch`, `websearch`, `question`, `todowrite`, `memory`, `session_search`, `attach_file`, `vision`, `skill`, `task`, `task_result`, `task_stop`, `ask_parent`, `steer`, `probe`, `answer_child`. Each is gated by a `tools.<key>` config flag (opt-out) and the approval model. See **[docs/tools.md](docs/tools.md)**.
+
+## Skills
+
+Skills are reusable instruction packs (a `SKILL.md` plus optional bundled reference files) that the agent pulls into context only when relevant — it sees a short index of available skills up front (Level 1), loads a skill's full body on demand (Level 2, which emits the `SKILL_LOADED` signal), and reads bundled references when needed (Level 3). They live in `.rubino/skills` / `~/.rubino/skills`, are gated by `tools.skill`, and expose usage/creation metrics. See **[docs/skills.md](docs/skills.md)**.
+
+## Fake LLM provider
+
+rubino ships a built-in **fake LLM provider** for tests, demos, and integration harnesses. Unlike a mocked adapter, the fake provider plugs into the *real* `Agent::Loop`, the real `ToolExecutor`, the real approvals/clarifications pipeline, and the real SSE stream — scenarios fake only what an LLM would produce (content / thinking chunks and `tool_call` requests). Downstream consumers hit the same surface they would against OpenAI/Anthropic, at zero token cost.
+
+```yaml
+model:
+  default: "fake/happy-path"
+
+providers:
+  fake:
+    scenarios_dir: "~/.rubino/scenarios"  # optional; defaults to built-in
+```
+
+Any `model_id` starting with `fake` is auto-routed to the fake provider. Because it can short-circuit tool decisions, it is **disabled by default** in `server` and `chat` — set `RUBINO_ALLOW_FAKE=1` to opt in. Production deployments must never set this.
+
+## HTTP API
+
+Start the bearer-protected JSON API server:
+
+```bash
+export RUBINO_API_KEY="$(openssl rand -hex 32)"
+export RUBINO_ENCRYPTION_KEY="$(openssl rand -base64 32)"   # required for OAuth routes
+rubino server --port 4820
+```
+
+Every request carries `Authorization: Bearer <RUBINO_API_KEY>` except `GET /v1/health` and `GET /v1/metrics`. The server binds `127.0.0.1` by default — pass `--host 0.0.0.0` (or set `RUBINO_API_HOST`) to expose it, and only do so behind TLS or a trusted segment. For a remote HTTP client the API can serve over a self-signed cert the client pins (`RUBINO_TLS=1`; read it with `rubino tls-cert`).
+
+Full request/response shapes, the error envelope, and SSE replay are in **[docs/api/v1.md](docs/api/v1.md)**.
+
+## Planned / on the roadmap
+
+These are designed-in but not fully wired yet — don't depend on them in production:
+
+- **MCP Support** — connect to Model Context Protocol servers via [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) ([docs/mcp.md](docs/mcp.md)).
+- **Multi-Agent** — Build / Plan / Explore agents with `@mention` routing ([docs/agents.md](docs/agents.md)).
+- **Plugin Hooks** — event hooks for extending behavior ([docs/plugins.md](docs/plugins.md)).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec               # run tests
+bundle exec rubino doctor   # verify setup
+```
+
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full dev/test/release flow.
+
+## License
+
+[MIT](LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/agents.md

@@ -0,0 +1,190 @@
+# Agents & Subagents
+
+rubino has two distinct multi-agent surfaces. Only the first one ships today:
+
+1. **Background subagents** (✅ shipping) — the agent delegates bounded sub-tasks
+   to isolated subagent runs via its `task` tool, and you supervise them with
+   `/agents` and `/reply`. This is the surface you will actually use.
+2. **Primary-agent switching** (⏳ not yet wired) — Tab-cycling between primary
+   agents and `@mention` routing. The machinery exists (`Agent::Router`,
+   `Agent::Definition`, `AgentRegistry`) but no call site passes an agent
+   definition yet, so the default (build) agent handles every turn. See
+   [the last section](#planned-primary-agent-switching--mentions-not-yet-wired).
+
+---
+
+## Background subagents (what ships)
+
+### How they start
+
+The MODEL spawns subagents with the `task` tool — you don't start them by hand;
+you ask for something parallelizable ("audit these 4 files in parallel") and the
+agent delegates. By default a `task` call runs in the **background**: it returns
+immediately with a task id (`sa_…`) and the subagent works on its own thread
+while the parent keeps going. When it finishes, the parent is notified with a
+`[background-task] <id> completed` message folded into its turn; the parent can
+also poll with `task_result(<id>)` or cancel with `task_stop(<id>)`.
+`background: false` runs the child inline instead (the parent blocks); it goes
+through the same nesting caps and ownership stamping as a background spawn.
+
+Each subagent is **isolated**: it gets a fresh session seeded with ONLY the
+prompt string — the parent transcript never leaks into the child, so the parent
+must put every needed file path / error / detail into the prompt.
+
+Built-in subagents the model can delegate to:
+
+| Subagent | Access | Description |
+|---|---|---|
+| **explore** | Read-only tools | Fast codebase search and navigation (max 20 turns) |
+| **general** | Full tools | Complex multi-step tasks (max 50 turns) |
+
+Background subagents live only in the current process (nothing is persisted —
+they die with the CLI/server process).
+
+### Nesting and caps
+
+Subagents keep the `task` tool, so a subagent CAN spawn its own subagents.
+The tree is bounded in one place (`Tools::BackgroundTasks#reserve`) by three
+config caps; when one is hit, the spawn is refused with a reason-specific
+message instead of fanning out unbounded work:
+
+| Config key | Default | Meaning |
+|---|---|---|
+| `tasks.max_depth` | `2` | Max nesting depth (human → child → grandchild) |
+| `tasks.max_children_per_node` | `3` | Max live children per parent |
+| `tasks.max_concurrent_total` | `8` | Max live subagents across the whole tree |
+
+### Statuses
+
+`/agents` and the live cards show each child's state:
+
+| Glyph | Status | Meaning | You act via |
+|---|---|---|---|
+| `●` | `running` | Working (last activity shown) | — |
+| `●` | `needs_approval` | A child tool needs your approval | `/agents <id>` |
+| `⛔` | `blocked_on_human` | Asked a question only YOU can answer (`ask_parent` escalated to the human) | `/reply <id> <answer>` |
+| `◷` | `blocked_on_parent` | Asked its agent-parent a question — the PARENT MODEL answers (`answer_child`); not your job unless you choose to step in with `/reply` | (optional) `/reply <id>` |
+| `◌` | `stopping` | Stop requested; unwinding at its next checkpoint | — |
+| `✓` | `done` | Finished; result available | `/agents <id>` |
+| `✗` | `failed` | Errored; error available | `/agents <id>` |
+| `⊘` | `stopped` | Cancelled by you (`--stop`); blocked descendants unwound; tools that completed before the stop may have left side effects | `/agents <id>` |
+
+A `⛔ N subagent waiting on you` marker persists until you `/reply`.
+
+### Supervising from the CLI: `/agents` and `/reply`
+
+```
+/agents                       # list background subagents (status, tools run, activity)
+/agents <id>                  # drill in: live watch while running, result/error when done
+/agents <id> --stop           # cancel a running subagent (blocked descendants unwind too)
+/agents <id> steer "note"     # park a note folded into the child's context at its next turn
+/agents <id> probe "question" # ephemeral read-only peek — nothing is saved to the child
+/reply <id> <answer>          # answer a child blocked on an ask_parent question
+/reply                        # bare: list the subagents currently blocked on you
+```
+
+`/tasks` is an alias for `/agents`. Stopping a node cancels its descendants'
+ask-gates too, so a blocking question anywhere in the subtree unwinds at once.
+
+**steer** is a persistent course-correction: the note enters the child's context
+at its next turn boundary and changes its trajectory.
+**probe** is ephemeral: a read-only side-inference over a snapshot of the
+child's transcript; the answer is shown to you and discarded — nothing is
+appended to the child's history.
+
+### Parent↔child channels (model-driven)
+
+The same three verbs are MODEL-callable tools, so an agent-parent can supervise
+its own children the way you supervise yours. All are gated by `tools.task` and
+**ownership-scoped at call time** — a caller can only touch its own direct
+children (see [tools.md](tools.md) for parameters):
+
+- **`steer(task_id, note)`** — park a persistent note on one of your running
+  children; it folds into the child's context at its next turn.
+- **`probe(task_id, question, live:)`** — check on a child without disturbing it.
+  `live: false` (default) is a FREE registry snapshot (status, tool count, last
+  activity, recent lines); `live: true` is a billed one-shot model peek over the
+  child's transcript, budgeted per child (`tasks.max_live_probes_per_child`,
+  default 5).
+- **`ask_parent(question, blocking:)`** — the child→parent escalation (only
+  available to subagents). `blocking: false` (default) keeps the child working
+  and folds the answer in later; `blocking: true` parks the child until answered,
+  bounded by `tasks.ask_parent_timeout` (default 900s — on expiry the child
+  proceeds with its best judgement instead of hanging).
+  Routing depends on who spawned the child: an agent-parent gets the question as
+  a note and answers with `answer_child` (child shows `◷ blocked_on_parent`); a
+  human-spawned child escalates straight to you (`⛔ blocked_on_human`, answered
+  via `/reply`). A parent that cannot answer from its own context escalates by
+  calling its OWN `ask_parent` — questions bubble up the tree to the human.
+- **`answer_child(task_id, answer)`** — the agent-parent's `/reply`: delivers
+  the answer into the asking child's context (unblocks a blocking ask, folds in
+  for a non-blocking one).
+
+### Approvals inside a background child
+
+When a background child's tool needs human approval, the child parks and the
+entry flips to `needs_approval` with the question/command shown on its card;
+resolve it via `/agents <id>`. In `yolo` mode the usual approval-skip rules
+apply (hardline floor still enforced — see [security.md](security.md)).
+
+---
+
+## Built-in agent definitions
+
+These definitions exist in `Agent::AgentRegistry` today. The two *subagents*
+are live as `task` targets; the two *primary* agents are only reachable as the
+default (`build`) or via the plan **mode** (`/mode plan`), not via agent
+switching; the *utility* agents are internal.
+
+| Agent | Type | Access | Description |
+|-------|------|--------|-------------|
+| **build** | primary | Full tools | Default development agent. Handles every turn today. |
+| **plan** | primary | Read-only | Analysis/planning definition (the shipping read-only surface is `/mode plan`). |
+| **explore** | subagent | Read-only | Fast codebase search and navigation (`task` target). |
+| **general** | subagent | Full tools | Complex multi-step tasks (`task` target). |
+| **compaction** | utility | None | Internal: compresses context. Hidden. |
+| **title** | utility | None | Internal: generates session titles. Hidden. |
+
+### Custom agents (via code)
+
+`AgentRegistry#register` accepts custom definitions programmatically:
+
+```ruby
+Rubino.agent_registry.register(
+  Rubino::Agent::Definition.new(
+    name: "security",
+    type: :subagent,
+    description: "Security-focused code review",
+    system_prompt: "You are a security expert…",
+    tools: %w[read grep glob],
+    permissions: { "shell *" => "deny", "write *" => "deny" }
+  )
+)
+```
+
+A registered `:subagent` definition immediately becomes a valid `task` target
+(it is advertised in the `task` tool's description). Each definition can carry
+its own model, system prompt, tool list (`:all`, `:read_only`, or names),
+pattern-based permission overrides (merged over the global rules by
+`ApprovalPolicy`), MCP-server scoping, and a `max_turns` budget.
+
+> **Note:** the `agents:` key in `config.yml` is reserved but **not yet read**
+> by the registry — declaring custom agents in config has no effect today.
+
+---
+
+## Planned: primary-agent switching & @mentions (not yet wired)
+
+> **Status:** the machinery exists — `Agent::Router` (@mention detection,
+> Tab-cycling, default routing) and the `agent_definition:` plumbing through the
+> runner — but **no call site passes an agent definition**, so Tab and
+> `@explore`/`@plan`/`@general` mentions currently do nothing. Use the
+> background-subagent surface above for real work.
+
+The intended design: press **Tab** to cycle through primary agents, or route a
+single message with an `@mention`:
+
+```
+you > @explore Where is the database connection configured?
+you > @plan How should we restructure the auth module?
+```