ollama_agent 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69d5c209f38109fb75cd33524df7cf31af937dbaa5b7b0c493973c6e7cc16c41
-  data.tar.gz: ef92101a3923debec6b193b1c9e56d1817e6154b44874daa0364a564d2336724
+  metadata.gz: 4d56b99449761370899bf612059caed5b1d7f58e0f4495b71cee23409b5cfb14
+  data.tar.gz: 3944154608557316fcb1b6126a39a9e94d63e8cf5fb86b41e96875c229c9a74c
 SHA512:
-  metadata.gz: 6f71a58b11c1a16eb5310313c8e3036323684861bd594c4c1dfc114504ca9f4a4b6cec3cef0309476d9be607aafd09fbaf01d4c5f8cea77b789708b7f8874ffe
-  data.tar.gz: e3f9747d242a68858beca29fc643711057f04d36f0bbd57929001b4feae56d8b6acd45969abf1adc64b57522f571e1f3e254142896c82b398cc21f0f9bced0e1
+  metadata.gz: da1673330de3f111382ec58b124b5b37fa4b973b4bdba0a1931449a06fc54963b0f5af1887ba5515d6ebd9fc4b56469c70164ef3378e68dbcc9cb5ca6f0518dd
+  data.tar.gz: c880764ea78000b140118e542cd77e1b8d3a8d06c37ba79cdfe2966c5bde21fb5bd43af5485799ef5044f37cdb55e5eba33a27b12a3bd2701bd7dced1e9f0ca2

data/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"721fd992-6855-4945-b1c5-b7cef534bb84","pid":1585817,"procStart":"20606262","acquiredAt":1778253145677}

data/.env.example

@@ -1,4 +1,21 @@
 # Example environment variables for OllamaAgent gem
+#
+# Dotenv precedence (highest first):
+#   1. XDG global config: ~/.config/ollama_agent/.env (or $OLLAMA_AGENT_DOTENV_PATH)
+#   2. Local project .env (loaded by ollama-client gem via Dotenv.overload)
+#   3. Shell ENV
+# To bypass the XDG global and use only the local project .env + shell ENV:
+#   OLLAMA_AGENT_USE_LOCAL_DOTENV=1
+#
+# Kernel runtime feature flag (see docs/USAGE.md):
+#   OLLAMA_AGENT_KERNEL=false   # default — legacy tool path
+#   OLLAMA_AGENT_KERNEL=shadow  # full saga FSM, no disk writes (observation)
+#   OLLAMA_AGENT_KERNEL=true    # mutations route through saga + atomic mutator
+#
+# Docker validator opt-in (see docs/agile/docker_spec_activation.md):
+#   DOCKER_AVAILABLE=true
+#   OLLAMA_AGENT_VALIDATOR_IMAGE=ollama-agent-validator:dev
+
 # Disable colored output (set to any value to respect https://no-color.org/)
 NO_COLOR=
 # Enable colored output (default: enabled). Set to "0" to disable.
@@ -11,8 +28,11 @@ OLLAMA_AGENT_THINKING_MARKDOWN=0
 OLLAMA_BASE_URL=https://ollama.com
 # API key for Ollama (if required)
 OLLAMA_API_KEY=your_api_key_here
-# Think parameter: true/false/high/medium/low (default: true)
+# Think parameter: true/false/high/medium/low (default: true). gpt-oss ignores booleans in the API;
+# when think resolves to true, we send low|medium|high (default medium, override below).
 OLLAMA_AGENT_THINK=1
+# gpt-oss only: low, medium, or high (used when OLLAMA_AGENT_THINK is true)
+# OLLAMA_AGENT_GPT_OSS_THINK=medium
 # Root directory for the agent (default: current working directory)
 OLLAMA_AGENT_ROOT=.
 # Debug mode (set to "1" for verbose output)

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## [Unreleased]
 
+## [1.0.1] - 2026-06-02
+
+### Added
+
+- **Tool `list_directory_contents`** (`OllamaAgent::Tools::FilesystemExplorer`) — inspect files and subdirectories inside the current workspace. All paths are resolved relative to the project root (`context[:root]` / `OLLAMA_AGENT_ROOT`); traversal outside that boundary (including `../../etc` and absolute paths) is rejected before the filesystem is touched. Returns `[DIR]` / `[FILE]` entries with byte sizes.
+- **Tool `calculate`** (`OllamaAgent::Tools::SafeCalculator`) — evaluate an arithmetic expression using a hand-written **Shunting-yard** tokenizer and RPN evaluator. Supports `+`, `-`, `*`, `/`, `**` (right-associative), parentheses, and unary `+`/`-`. **No `eval` is used at any point.** Right-associativity of `**` is correct: `2 ** 3 ** 2` → `512`. Division by zero returns a non-finite message rather than raising.
+- Both tools are available in **all permission profiles** (`read_only`, `standard`, `developer`, `full`), registered in `CORE_TOOLS` so they appear in the Ollama tool schema automatically, and dispatched through the existing `SandboxedTools#execute_tool` loop.
+- `examples/agentic_tool_calling.rb` — runnable demo covering filesystem inspection, arithmetic evaluation, and a combined prompt that chains both tools. Mirrors the KDnuggets *Easy Agentic Tool Calling with Gemma 4* article pattern, adapted to the `OllamaAgent` Ruby runtime.
+- `docs/TOOLS.md` — new **Built-in agentic tools** section documenting `list_directory_contents` and `calculate` with Ruby API examples.
+
+### Removed
+
+- **`trading_agent` extraction**: Removed the nested `trading_agent/` project/gem from the `ollama_agent` repository to a dedicated standalone sibling repository (`trading_agent`).
+
+### Documentation
+
+- **README:** New **Reasoning / thinking output** section—how to set `think` (including **GPT-OSS** `low`/`medium`/`high`), streaming vs one-shot, display env vars, troubleshooting when **Thinking** is missing, Gemma-style tags, and **`Runner.build`** example. **`OLLAMA_AGENT_STREAM`** and GPT-OSS notes added to the environment table; Ollama Cloud example sets **`OLLAMA_AGENT_THINK`**.
+
+### Fixed
+
+- **RuboCop and Style Cleanups**: Fixed 424 RuboCop offenses and refined `.rubocop.yml` parameters.
+- **CI/CD Correction**: Removed obsolete nested `trading_agent` job from CI/CD main workflow.
+- **Thinking display:** Coerce non-string `message.thinking` from the API (e.g. array-shaped chunks) before deciding whether reasoning is present (`GemmaThoughtContentParser.merge_into_message_data!` + `ChatStreamThinkingFormat`). After a **streaming** chat completion, run the same merge so content-embedded reasoning tags still split into **Thinking** / **Assistant**.
+
 ## [1.0.0] - 2026-04-11
 
 First **stable** release under [Semantic Versioning](https://semver.org/): within the **`1.x`** series, the documented public Ruby API and CLI behavior are intended to remain **backwards compatible** except where called out in the changelog.

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+## Tests
+
+- Run **`bundle exec rspec`** before opening a PR.
+- Prefer **behavior-focused** examples; stub external binaries (`patch`, `rg`) when asserting failure paths.
+- Add or extend specs when you change the agent loop, tool schemas, sandbox, or budget/loop detection.
+
+## Style
+
+- Run **`bundle exec rubocop`**. The repository is moving toward a clean full-tree baseline; CI currently runs RuboCop with **`continue-on-error: true`** until legacy offenses are cleared.
+- Add **`# frozen_string_literal: true`** to new Ruby files.
+
+## Error handling
+
+- Do **not** use **`rescue Exception`** (it catches `Interrupt` / `SignalException`). Rescue **`StandardError`** (or narrower types) and either re-raise, wrap in **`OllamaAgent::Error`**, or log and return a safe value—never swallow signals.
+
+## Architecture notes
+
+- **Tools:** Prefer **`OllamaAgent::Tools::BuiltInSchemas.register`** for new first-party tool schemas instead of hard-coding branches in unrelated modules.
+- **Logging:** Use the agent’s **`Logger`** (or `OllamaAgent::Agent`’s `logger` reader) instead of bare **`warn`** for user-relevant messages so embedders can stub or redirect output.
+
+Thank you for helping improve `ollama_agent`.

data/README.md

@@ -4,12 +4,29 @@ Version: 1.0.0
 
 Ruby gem that runs a **CLI coding agent** against a local [Ollama](https://ollama.com) model. It exposes tools to **list files**, **read files**, **search the tree** (ripgrep or grep), and **apply unified diffs** so the model can make small, reviewable edits.
 
+## Contents
+
+- [Features](#features)
+- [Kernel runtime (deterministic execution)](#kernel-runtime-deterministic-execution) — see also [CAPABILITIES](docs/CAPABILITIES.md), [CLI](docs/CLI.md), [OPERATIONS](docs/OPERATIONS.md), [USAGE](docs/USAGE.md)
+- [Requirements](#requirements)
+- [Security and sandbox](#security-and-sandbox)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Agentic tool calling](#agentic-tool-calling-local-environment-tools)
+- [Skills](#skills-deterministic-json-contract-pipelines)
+- [Troubleshooting](#troubleshooting)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [License](#license)
+
 ## Features
 
 - Tool `list_files` – list project files.
 - Tool `read_file` – read file contents.
 - Tool `search_code` – search code with ripgrep or grep.
 - Tool `edit_file` – apply unified diffs safely.
+- Tool `list_directory_contents` – sandboxed filesystem inspection; see [Agentic tool calling](#agentic-tool-calling-local-environment-tools).
+- Tool `calculate` – safe arithmetic evaluator (Shunting-yard, no `eval`); see [Agentic tool calling](#agentic-tool-calling-local-environment-tools).
 - CLI built with Thor, entry point `exe/ollama_agent`.
 - **`self_review`** – self-review / improvement with a **`--mode`**:
   - **`analysis`** (default, alias `1`) — read-only tools; report only; no writes.
@@ -19,9 +36,34 @@ Ruby gem that runs a **CLI coding agent** against a local [Ollama](https://ollam
 - **`orchestrate`** / **`OLLAMA_AGENT_ORCHESTRATOR=1`** — optional **orchestrator** tools to probe and delegate to other local CLI agents (see [Orchestrator](#orchestrator-external-cli-agents)); **`agents`** lists availability.
 - **Ruby API** — embed **`Runner`**, **`Agent`**, custom tools, hooks, sessions, and (optionally) **`ToolRuntime`**; see [Library usage (Ruby)](#library-usage-ruby).
 
+## Kernel runtime (deterministic execution)
+
+**Documentation (post-kernel):** [Capability matrix](docs/CAPABILITIES.md) · [CLI reference](docs/CLI.md) · [Operations / incidents](docs/OPERATIONS.md) · [Usage guide](docs/USAGE.md).
+
+The **runtime kernel** is an optional execution layer behind `OLLAMA_AGENT_KERNEL`. It wraps file mutations in a **saga-style finite state machine**: intent reservation, **atomic writes** (CAS + pre-image hashes), ownership checks against compiled rules, **SQLite-backed WAL** and sagas, isolated post-mutation validation, and compensation on failure. The workspace root remains the **trust boundary**; the kernel adds structured **ownership** and **fencing** so replays and automation stay auditable. When cloud or validator paths fail, **circuit-breaker style** escalation limits (see the rollout runbook) keep bad states from compounding.
+
+| `OLLAMA_AGENT_KERNEL` | Behavior |
+| --- | --- |
+| unset / `false` (default) | Legacy tool paths; kernel pipeline is not used for tool routing. |
+| `shadow` | Same routing as `true`, but the pipeline runs in **shadow** mode: saga + WAL + observability run, while workspace bytes for certain mutations stay off the “real” path (see runbook). |
+| `true` / `1` | Tool intents for configured mutation tools go through **`OllamaAgent::Runtime::KernelPipeline`**. |
+
+**Quick start (kernel on):**
+
+```bash
+OLLAMA_AGENT_KERNEL=true bundle exec ollama_agent ask "Your task"
+```
+
+Design notes and roadmap items live in **`docs/new_features_plan_v2.md`**. Operational rollout, shadow mode, and rollback expectations are in **`docs/agile/release_rollout_runbook.md`** (incident SQL, health JSON, and compaction details are expanded in **`docs/OPERATIONS.md`**). For **E7 validator activation** (Docker-backed isolated checks), see **`docs/agile/docker_spec_activation.md`**.
+
+**Compaction and disk bounds:** long-lived workspaces accumulate kernel SQLite rows and content-addressed blobs. Use **`OllamaAgent::Runtime::Compactor`** (logical `current_epoch` only — no wall clock) to prune sealed sagas, cold-archive old WAL rows into `event_store_archive.db`, purge expired recovery leases and stale intent reservations, and unlink blob files not referenced by compensations or in-flight mutation WAL payloads. **`OllamaAgent::Runtime::CompactorRunner`** wraps the compactor with an epoch interval for daemon loops (opt-in; nothing starts automatically).
+
+**Permission unification:** when `OLLAMA_AGENT_KERNEL` is on and `config/ollama_agent/owners.yml` exists, **`OllamaAgent::Runtime::PermissionBridge`** reconciles legacy **`Runtime::Permissions` / `Runtime::Policies`** with **`Security::OwnershipIndex`** + **`CriticalityPolicy`** before pipeline execution. On divergence the bridge logs and **prefers the kernel decision** (stricter path wins). `OllamaAgent::PermissionConflictError` is raised only by the strict `#allow_mutation?` API for tests and diagnostics. With the kernel **off**, only the legacy permission path runs (no bridge).
+
 ## Requirements
 
 - Ruby ≥ 3.2 (enforced in the gemspec as `required_ruby_version`)
+- **Runtime kernel (SQLite):** the **sqlite3** gem is a runtime dependency; kernel storage uses `event_store.db` and `runtime.db` under `.ollama_agent/kernel/` in the configured project root.
 - **Local:** Ollama running and a capable tool-calling model, **or**
 - **Ollama Cloud:** API key and a cloud-capable model name (see below)
 
@@ -30,6 +72,15 @@ Ruby gem that runs a **CLI coding agent** against a local [Ollama](https://ollam
 - **`patch`** — required for `edit_file` (GNU `patch` on `PATH`). On Windows, use Git Bash, WSL, GnuWin32, or another environment that provides `patch`.
 - **`rg` (ripgrep) or `grep`** — text mode for `search_code` needs at least one of these on `PATH` (ripgrep is preferred when present).
 
+## Security and sandbox
+
+- **Project root** — File tools and search are constrained to the configured workspace (`--root` / `OLLAMA_AGENT_ROOT`). Treat that directory as the trust boundary: only aim the agent at trees you are willing to modify.
+- **`list_directory_contents`** — Paths are resolved with `File.expand_path` relative to the project root and rejected before the filesystem is touched if they escape that boundary. `../../etc`, `/etc`, and any other traversal are caught by a prefix check, not a regex.
+- **`calculate`** — Uses a hand-written tokenizer and Shunting-yard evaluator. `eval` is never called. Only numeric literals and the operators `+`, `-`, `*`, `/`, `**` are accepted; any other character is an error.
+- **`run_shell` (optional tool)** — Commands are parsed into an argument vector (no shell) and must match an allowlist; a denylist blocks obviously dangerous patterns. You can still shoot yourself in the foot with an allowed prefix (for example `git` with destructive subcommands), so keep profiles and permissions tight in automated setups.
+- **Timeouts** — Text search honors `OLLAMA_AGENT_SEARCH_TIMEOUT_SEC` (default 120). Shell execution has its own per-invocation timeout.
+- **Logging** — Budget, loop-detection, and `list_local_model_names` failures go through Ruby’s `Logger` (stderr by default). Set `OLLAMA_AGENT_LOG_LEVEL=debug` or `OLLAMA_AGENT_DEBUG=1` for more detail.
+
 ## Installation
 
 From RubyGems (when published) or from this repository:
@@ -73,6 +124,21 @@ Long-running models (slow local inference):
 bundle exec ruby exe/ollama_agent ask --timeout 300 "Your task"
 ```
 
+### Agent budget (steps, tokens, cost)
+
+Each **model round-trip** that runs during a session counts as one **step** toward `OLLAMA_AGENT_MAX_TURNS` (default **64**), enforced together with token and optional cost limits in `OllamaAgent::Core::Budget`. Exploratory tasks that **list, read, and search** across a **large repository** can burn through steps quickly; if you see `budget exceeded — step limit (64)`, raise the limit—for example:
+
+```bash
+export OLLAMA_AGENT_MAX_TURNS=128
+bundle exec ruby exe/ollama_agent ask "Your wide-ranging task"
+```
+
+Narrower prompts, **`--read-only`**, or a smaller `--root` also reduce step usage. With **`OLLAMA_AGENT_DEBUG=1`**, the agent prints an extra hint when the **maximum tool rounds** for a run are reached.
+
+### `search_code` and regex patterns
+
+In **text** mode, the tool passes your pattern to **ripgrep** (or **grep**). Patterns are **regular expressions**: literal parentheses, brackets, and unbalanced groups can trigger errors (for example `unclosed group`). Escape metacharacters or use **fixed-string** mode when your tool schema exposes it.
+
 **Plain line REPL** (no TUI boxes / markdown shell): use **`ask` (or `orchestrate`) with `-i` and without `--tui`**—for example when you omit the query you must opt out of the default TUI this way:
 
 ```bash
@@ -101,19 +167,62 @@ bundle exec ruby exe/ollama_agent improve --apply
 
 For mode 3, `-y` skips all patch prompts; `--no-semi` prompts for every patch when not using `-y`.
 
-With a **thinking-capable** model, enable reasoning output:
+### Reasoning / thinking output
+
+On [thinking-capable models](https://docs.ollama.com/capabilities/thinking), Ollama can return **reasoning** separately from the final answer (`message.thinking` vs `message.content`). The CLI labels them **Thinking** (dim) and **Assistant** (green / Markdown).
+
+#### Enable `think` on the request
+
+The agent sends Ollama’s `think` field only when you set it (CLI or env). If you omit it, the server uses its own defaults—and some models then omit or change reasoning in the response.
+
+| You want | CLI | Environment |
+|----------|-----|-------------|
+| Reasoning on (typical Qwen / DeepSeek-style) | `--think true` | `OLLAMA_AGENT_THINK=true` or `1` |
+| Reasoning off | `--think false` | `OLLAMA_AGENT_THINK=false` or `0` |
+| **GPT-OSS** style levels | `--think low`, `medium`, or `high` | `OLLAMA_AGENT_THINK=medium` (example) |
+
+Examples:
 
 ```bash
 OLLAMA_AGENT_THINK=true bundle exec ruby exe/ollama_agent ask -i
-# or
 bundle exec ruby exe/ollama_agent ask -i --think true
+# GPT-OSS: prefer a level, not only true/false
+bundle exec ruby exe/ollama_agent ask --think medium "Your task"
+```
+
+#### Streaming vs one-shot (default)
+
+| Mode | Flags | What you see |
+|------|--------|----------------|
+| **One-shot** (default) | neither `--stream` nor `OLLAMA_AGENT_STREAM=1` | Each model round completes over HTTP; **Thinking** / **Assistant** are printed from the assembled **`message`** (including Gemma-style reasoning tags stripped from `content` when the API omits `thinking`). |
+| **Streaming** | `--stream` or `OLLAMA_AGENT_STREAM=1` | Reasoning streams in **dim** text under one **Thinking** line, then **Assistant** and the reply stream—similar to Cursor. Uses `hooks[:on_thinking]` on the ollama-client chat stream (see `OllamaAgent::OllamaChatThinkingStreamPatch`). |
+
+```bash
+OLLAMA_AGENT_THINK=medium OLLAMA_AGENT_STREAM=1 bundle exec ruby exe/ollama_agent ask "Your task"
 ```
 
-The CLI uses **ANSI colors** on a TTY (banner, prompt, patch prompts). **Assistant replies** are rendered as **Markdown** (headings, lists, bold, code fences) via `tty-markdown` when stdout is a TTY and **`NO_COLOR`** is unset. Disable Markdown rendering with **`OLLAMA_AGENT_MARKDOWN=0`**. Disable all colors with **`NO_COLOR`** or **`OLLAMA_AGENT_COLOR=0`**.
+**Note:** Subscribing only to `on_thinking` does **not** enable the streaming chat path; the agent uses streaming when something listens for **`on_token`** (the console streamer registers both). See CHANGELOG **1.0.0** if you embed the library.
+
+#### Display style (TTY)
+
+By default **`OLLAMA_AGENT_THINKING_STYLE=compact`**: one **Thinking** header per `ask` run; later reasoning chunks in the same run are separated by **blank lines** only (including after tool rounds). **`OLLAMA_AGENT_THINKING_STYLE=framed`** repeats the full boxed banner per message. Thinking body is **plain dim** unless **`OLLAMA_AGENT_THINKING_MARKDOWN=1`**.
+
+The CLI uses **ANSI colors** on a TTY (banner, prompt, patch prompts). **Assistant** replies use **Markdown** via `tty-markdown` when stdout is a TTY and **`NO_COLOR`** is unset. Disable Markdown with **`OLLAMA_AGENT_MARKDOWN=0`**; disable colors with **`NO_COLOR`** or **`OLLAMA_AGENT_COLOR=0`**.
 
-When **thinking** is enabled, internal reasoning is shown under a **Thinking** label; the user-facing reply is labeled **Assistant** in green when the model returns both fields. By default (**`OLLAMA_AGENT_THINKING_STYLE=compact`**, Cursor-like), one **Thinking** header is printed per `ask` run and every later reasoning chunk in that run is appended with **blank lines only** (no repeated banner, no rule lines)—including after turns where the model printed tool JSON or other non-empty `content`. Set **`OLLAMA_AGENT_THINKING_STYLE=framed`** for the legacy boxed style (banner + long rulers on every assistant message). Thinking body text is **plain dim** by default. Set **`OLLAMA_AGENT_THINKING_MARKDOWN=1`** to render thinking through Markdown too (muted colors).
+#### If you see no **Thinking** block
 
-With **`--stream`** / **`OLLAMA_AGENT_STREAM=1`**, reasoning streams in **dim** text under a single **Thinking** line, then **`Assistant`** and the reply stream in normal styling—closer to Cursor than printing everything as one token stream. (This uses a small hook on ollama-client’s chat stream; `hooks[:on_thinking]` is also emitted for custom subscribers.)
+1. **Set `think` explicitly**—especially for **GPT-OSS** (`low` / `medium` / `high`).
+2. **Confirm the model returns `message.thinking`** (e.g. `curl` / `ollama` CLI against `/api/chat` with the same `think` value). If the API never sends `thinking`, the agent has nothing to show.
+3. **Try streaming** (`--stream` or `OLLAMA_AGENT_STREAM=1`) if you want live reasoning tokens.
+4. **Embedded reasoning in `content`:** Some templates (e.g. Gemma) put tags such as `<|channel>thought` … `<channel|>` or `<redacted_thinking>` … `</redacted_thinking>` inside `content`. The agent strips those into **Thinking** when present (`OllamaAgent::GemmaThoughtContentParser`). If your model uses different delimiters, reasoning may stay inside the main reply until parsers are extended.
+
+#### Ruby API
+
+```ruby
+OllamaAgent::Runner.build(stream: true, think: "medium").run("Your task")
+```
+
+Custom subscribers can attach to **`hooks[:on_thinking]`** and **`hooks[:on_token]`** on the same **`Runner`** instance (see `OllamaAgent::Streaming::Hooks`).
 
 ### Ollama Cloud
 
@@ -126,9 +235,63 @@ With **`--stream`** / **`OLLAMA_AGENT_STREAM=1`**, reasoning streams in **dim**
 export OLLAMA_BASE_URL="https://ollama.com"
 export OLLAMA_API_KEY="your_key"
 export OLLAMA_AGENT_MODEL="gpt-oss:120b-cloud"   # example; pick a cloud model from `ollama list` / the catalog
+# Reasoning for GPT-OSS: set a level (see "Reasoning / thinking output" above)
+export OLLAMA_AGENT_THINK=medium
+bundle exec ruby exe/ollama_agent ask "Your task"
+```
+
+#### Multi-Key Provider Credential Orchestration & Failover
+
+To handle rate limits (RPM/TPM window exhaustion), daily quotas, or network timeouts when using Ollama Cloud (or other providers like OpenAI and Anthropic), you can configure a thread-safe, quota-aware **Credential Pool** with automatic reactive failover.
+
+The pool can be configured dynamically via the Ruby API or auto-detected from environment variables.
+
+##### Environment Auto-Detection
+
+If no explicit credentials are passed in, `ollama_agent` automatically scans the environment for keys indexed `1` to `5` and initializes a `CredentialPool`:
+
+* **Ollama Cloud**: Configure keys `OLLAMA_API_KEY_1` through `OLLAMA_API_KEY_5`. When any of these are present, requests are routed to `"https://api.ollama.com"` (aliased as `"ollama_cloud"`).
+* **OpenAI**: Configure keys `OPENAI_API_KEY_1` through `OPENAI_API_KEY_5`.
+* **Anthropic**: Configure keys `ANTHROPIC_API_KEY_1` through `ANTHROPIC_API_KEY_5`.
+
+Example for Ollama Cloud:
+```bash
+export OLLAMA_API_KEY_1="ollama_key_abc123"
+export OLLAMA_API_KEY_2="ollama_key_def456"
 bundle exec ruby exe/ollama_agent ask "Your task"
 ```
 
+##### Ruby API Configuration
+
+You can also pass a structured array of credential hashes to `OllamaAgent::Runner.build`:
+
+```ruby
+runner = OllamaAgent::Runner.build(
+  credentials: [
+    {
+      id: "ollama-cloud-primary",
+      provider: "ollama_cloud",
+      api_key: "ollama_...",
+      weight: 2, # weighted round-robin priority (default: 1)
+      limits: { rpm: 10, tpm: 10000, daily_tokens: 1000000 } # automatic quota tracking
+    },
+    {
+      id: "openai-backup",
+      provider: "openai",
+      api_key: "sk-...",
+      weight: 1
+    }
+  ]
+)
+runner.run("Your task")
+```
+
+##### Failover Behavior
+1. **Weighted Round-Robin**: Requests are balanced across healthy and available credentials.
+2. **Quota Tracking**: Daily token/request and RPM/TPM sliding windows are tracked locally.
+3. **Reactive Failover**: If a key encounters a rate limit (`HTTP 429`), temporary provider error (`HTTP 5xx`), or quota exhaustion, it is temporarily cooled down and the request is retried with the next available key.
+4. **Permanent Disabling**: If a key encounters an authentication failure (`HTTP 401` or `HTTP 403`), it is permanently disabled to prevent dead-key hammering.
+
 ### Environment
 
 | Variable | Purpose |
@@ -147,7 +310,8 @@ bundle exec ruby exe/ollama_agent ask "Your task"
 | `OLLAMA_AGENT_MARKDOWN` | Set to `0` to disable Markdown formatting of assistant replies (plain text only) |
 | `OLLAMA_AGENT_THINKING_STYLE` | `compact` (default) = one **Thinking** label per run, blank lines between later reasoning chunks; `framed` = repeat full banner/rulers each message |
 | `OLLAMA_AGENT_THINKING_MARKDOWN` | Set to `1` to render **thinking** text with Markdown (muted); default is plain dim text |
-| `OLLAMA_AGENT_THINK` | Model **thinking** mode for compatible models: `true` / `false`, or `high` / `medium` / `low` (see ollama-client `think:`). Empty = omit (server default). |
+| `OLLAMA_AGENT_STREAM` | Set to `1` to stream tokens and reasoning to stdout (same as CLI **`--stream`** on `ask` / `self_review` / `improve`). |
+| `OLLAMA_AGENT_THINK` | Model **thinking** mode for compatible models: `true` / `false`, or `high` / `medium` / `low` (see ollama-client `think:`). Empty = omit (server default). **GPT-OSS:** use `low` / `medium` / `high`. |
 | `OLLAMA_AGENT_PATCH_RISK_MAX_DIFF_LINES` | Max changed-line count before a diff is treated as "large" for semi-auto patch risk (default **80**) |
 | `OLLAMA_AGENT_INDEX_REBUILD` | Set to `1` to drop the cached Prism Ruby index before the next symbol search in this process |
 | `OLLAMA_AGENT_RUBY_INDEX_MAX_FILES` | Max `.rb` files to parse per index build (default **5000**) |
@@ -189,6 +353,59 @@ Use the **`orchestrate`** command (or **`OLLAMA_AGENT_ORCHESTRATOR=1`** with **`
 - Adjust **`argv` / `version_argv`** in YAML to match your real CLI (vendor flags differ). If a tool has no stable non-interactive mode, do not expose it in the registry.
 - Tool contract version: **`OllamaAgent::ORCHESTRATOR_TOOLS_SCHEMA_VERSION`**.
 
+### Agentic tool calling (local environment tools)
+
+Two built-in tools let the model observe its environment and compute precisely — the pattern described in [Easy Agentic Tool Calling with Gemma 4](https://www.kdnuggets.com/easy-agentic-tool-calling-with-gemma-4) — adapted here for the Ruby runtime.
+
+#### `list_directory_contents`
+
+Lists files and subdirectories inside the current workspace. The model decides when to inspect the environment rather than guessing at what exists.
+
+```bash
+bundle exec ruby exe/ollama_agent ask \
+  "What scripts are in the current folder, and which one looks like it handles CSV processing?"
+```
+
+All paths are sandboxed to `OLLAMA_AGENT_ROOT`. Traversal attempts (`../../etc`, absolute paths) are rejected before the filesystem is touched.
+
+#### `calculate`
+
+Evaluates an arithmetic expression using a Shunting-yard parser. The model offloads precision arithmetic instead of computing in its weights.
+
+```bash
+bundle exec ruby exe/ollama_agent ask \
+  "What is the standard deviation of 12, 18, 23, 29, 31, 35, 44, 47 — compute it step by step using the formula."
+```
+
+Supports `+`, `-`, `*`, `/`, `**` (right-associative), parentheses, and unary `+`/`-`. No `eval`.
+
+#### Combining both tools
+
+The model can chain the two tools in a single request — inspect the workspace first, then compute something about what it found:
+
+```bash
+bundle exec ruby exe/ollama_agent ask \
+  "Look at the files in the current folder and tell me the total size in kilobytes, rounded to two decimal places."
+```
+
+Internally: the model calls `list_directory_contents` to get byte sizes, then calls `calculate` with the sum and division by 1024.
+
+#### Ruby API
+
+```ruby
+require "ollama_agent"
+
+runner = OllamaAgent::Runner.build(root: Dir.pwd)
+
+# Filesystem inspection
+puts runner.run("What files are in lib/ollama_agent/tools/?")
+
+# Arithmetic
+puts runner.run("What is (412 + 1834 + 10786 + 88 + 2210) / 1024, rounded to 2 decimal places?")
+```
+
+See `examples/agentic_tool_calling.rb` for a runnable end-to-end demo.
+
 ### Library usage (Ruby)
 
 Most of this README is **CLI-first** (commands and environment variables above). The same capabilities exist as **Ruby APIs**—the [Features](#features) list (file tools, `self_review` / `improve`, orchestrator, skills, etc.) is implemented under `lib/ollama_agent/`. For a **layer diagram** (agent → tools → hooks → session), see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
@@ -247,6 +464,75 @@ last = OllamaAgent::ToolRuntime::Loop.new(
 # last => e.g. { "status" => "done", "echo" => "bye" }
 ```
 
+## Skills (deterministic JSON-contract pipelines)
+
+Skills are single-purpose generators that bypass the tool-calling agent loop and
+return **strict JSON** validated against a schema. They are meant for pipelines
+that need predictable, parseable output — code review, refactoring suggestions,
+performance audits, debugging triage — without the unpredictability of free-form
+LLM prose.
+
+Built-in skills:
+
+- `architecture_refactor` — restructure code without changing behavior
+- `performance_optimizer` — identify bottlenecks and emit optimized code
+- `debug_engineer` — root-cause a bug and propose a fix
+- `feature_builder` — design and implement a production-ready feature
+
+Each skill:
+
+1. Renders a deterministic prompt (LLM `temperature: 0` by default).
+2. Extracts the first balanced JSON object from the response (tolerates prose
+   and ```` ```json ```` fences).
+3. Validates against the skill's `SCHEMA` and raises `ContractError` on mismatch.
+
+### CLI
+
+```bash
+# list registered skills
+ollama_agent skill list
+
+# run a single skill
+ollama_agent skill run architecture_refactor --code-file lib/orders/manager.rb
+
+# compose a pipeline; later skills receive earlier outputs merged in
+ollama_agent skill pipeline architecture_refactor performance_optimizer \
+  --code-file lib/exit_management.rb
+```
+
+Override the model with `--model`, `OLLAMA_AGENT_SKILL_MODEL`, or
+`OLLAMA_AGENT_MODEL`.
+
+### Ruby
+
+```ruby
+result = OllamaAgent::Skills::ArchitectureRefactorer.new.call(
+  code: File.read("lib/orders/manager.rb")
+)
+# => { folder_structure: [...], architecture_notes: "...", refactored_code: "..." }
+
+OllamaAgent::Skills::Runner.new(
+  [:architecture_refactor, :performance_optimizer]
+).call(code: File.read("lib/exit_management.rb"))
+```
+
+Inject your own LLM client (anything responding to `#generate(prompt) → String`)
+in tests:
+
+```ruby
+class FakeLlm
+  def generate(_prompt)
+    '{"bottlenecks": [], "optimizations": [], "optimized_code": "x"}'
+  end
+end
+
+OllamaAgent::Skills::PerformanceOptimizer.new(llm: FakeLlm.new).call(code: "...")
+```
+
+By default skills run against the local Ollama provider (local-first, auditable).
+They go through `OllamaAgent::Providers::Registry`, so any registered provider
+(OpenAI, Anthropic, custom) is usable by passing your own `LlmClient`.
+
 ## Troubleshooting
 
 - **Use a tool-capable model** — Set `OLLAMA_AGENT_MODEL` to a model that supports function/tool calling (e.g. a recent coder-tuned variant). If the model only prints `{"name": "read_file", ...}` in plain text, tools never run unless you enable `OLLAMA_AGENT_PARSE_TOOL_JSON=1`.
@@ -267,6 +553,8 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+Ongoing refactors (contributors): the **`Agent`** class is a thin façade over **`TurnLoop`**, **`ChatCoordinator`**, session/client wiring, and **`Tools::BuiltInSchemas`** so new behavior should land in those collaborators instead of growing monolithic methods. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ### CI and RubyGems release
 
 - **CI** — [`.github/workflows/main.yml`](.github/workflows/main.yml) runs **RSpec** and **RuboCop** on pushes to `main` / `master` and on pull requests (Ruby **3.3.4** and **3.2.0**).

data/Rakefile

@@ -3,6 +3,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+Dir.glob(File.expand_path("lib/tasks/*.rake", __dir__)).each { |path| load path }
+
 RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"

data/config/ollama_agent/owners.yml

@@ -0,0 +1,53 @@
+# Example ownership graph for a typical Rails app (workspace-relative prefixes, no trailing slashes).
+# Copy or extend for your repo; compile with OllamaAgent::Security::OwnershipCompiler.
+
+version: 1
+rules:
+  - prefix: app
+    owner: application
+    mutable_in_modes: [normal, replay, validation, dry_run]
+    criticality: routine
+    forbidden: false
+    children:
+      - prefix: app/models
+        owner: domain
+        mutable_in_modes: [normal, replay, validation]
+        criticality: sensitive
+        children: []
+
+  - prefix: config
+    owner: platform
+    mutable_in_modes: [normal, replay, validation, dry_run]
+    criticality: sensitive
+    children: []
+
+  - prefix: db/migrate
+    owner: data
+    mutable_in_modes: [normal, validation]
+    criticality: critical
+    children: []
+
+  - prefix: lib
+    owner: shared_libraries
+    mutable_in_modes: [normal, replay, validation, dry_run]
+    criticality: routine
+    children: []
+
+  - prefix: log
+    owner: observability
+    mutable_in_modes: [normal, dry_run]
+    criticality: routine
+    children: []
+
+  - prefix: tmp
+    owner: scratch
+    mutable_in_modes: [normal, dry_run]
+    criticality: routine
+    children: []
+
+  - prefix: .env
+    owner: secrets
+    mutable_in_modes: [normal, replay, validation, dry_run]
+    criticality: critical
+    forbidden: true
+    children: []

data/containers/ollama_agent-verification-sandbox.Dockerfile

@@ -0,0 +1,16 @@
+# Minimal sandbox for post-condition / isolated validation (array-exec only at the Docker CLI).
+# Build: docker build -f containers/ollama_agent-verification-sandbox.Dockerfile -t ollama-agent-validator:local .
+#
+# ruby:3.3-slim is smaller than the default non-slim image while keeping glibc compatibility.
+FROM ruby:3.3-slim-bookworm
+
+RUN groupadd --system --gid 65532 sandbox \
+  && useradd --system --uid 65532 --gid sandbox --home-dir /workspace --shell /usr/sbin/nologin sandbox
+
+WORKDIR /workspace
+
+# Replace with a concrete argv at `docker run ... image <cmd...>`; this is only a smoke default.
+ENTRYPOINT []
+CMD ["ruby", "-rjson", "-e", "puts JSON.dump({ok: true})"]
+
+USER sandbox