zephira 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1c50d16206adc052c5236333defc539edcd65a533e975794f781427f7364fd10
+  data.tar.gz: 69fecd0054fba2316e0aaa02ef529742c5a9de2258091eedada942df3c9f8425
+SHA512:
+  metadata.gz: 20b9495103c802b063d71f197e55f248c0eebc7f1b07d74ca0e41ebd0219a450976e7b246dec0c7d72cdcbbe659b68f8db54443c224d9291abf24df6472fbb40
+  data.tar.gz: 859aa00aa284fc405df4f7079cdf322640228986f141ab1a0142743af6c83faffd65ea68a9ba09a4fac1b64be497feaadb81cfbc79b4cb88eec5f9aa0e4841a7

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Zephira Changelog
+
+## [Unreleased]
+
+### Added
+- Concurrent execution of read-only tool calls within a single model turn (`web_search`, `read_file`, `code_search`, `list_directory`, `memory_read`, `memory_list`). Mutating tools still run sequentially in declared order.
+- `Tools::BaseTool.read_only?` class method — tools opt in by overriding it. Default is `false`.
+- `Zephira::Tokens` module — single token-estimator shared by `History` and `Agent`.
+- `Zephira::Agent::Status` extracted to its own file.
+- `Zephira::Tools::MemoryStore` shared helper backing the four memory tools.
+- Per-model `backend` override on `BaseModel` so future provider classes can be added without forking the inference loop.
+
+### Changed
+- Renamed `/models` slash command to `/model`.
+- `Agent#run_loop` decomposed into focused helpers (`print_intro`, `render_status_bar`, `process_user_message`, `run_inference_with_spinner`, etc.).
+- Cached `uname -a` and `pwd` at agent init instead of shelling out per request.
+- Inference loop uses iteration instead of recursion for tool-call chains; max-iter guards become trivial to add.
+- Memory tools now load YAML via `YAML.safe_load_file`.
+- Backend `agent` is passed per call rather than held as an ivar; rescue paths nil-guard the agent.
+- Debug toggle moved from raw `ENV["DEBUG"]` to `Config.read("ZEPHIRA_DEBUG")` for consistency.
+- `code_search` tool uses POSIX `command -v` instead of `which`.
+- Spinner elapsed-time updates now go through the public `TTY::Spinner#update` API instead of reaching into private `@tokens` state.
+- `update_file` now allows empty content (declarative `allow_empty: true` is now the single source of truth).
+
+### Fixed
+- JSON parse failures on tool arguments now log via `agent.logger.error` with the raw payload instead of being silently swallowed.
+
+### Tests
+- Added thread-safe stdout/stderr silencer in `spec_helper` (`:show_output` opt-out).
+- Added default `Config.read` stub in `spec_helper` (`:real_config` opt-out).
+- Broadened error-path coverage for file tools and `Agent::Status`.
+- Suite: 422 examples, 0 failures, ~96% line coverage.
+
+## 0.1.0
+
+In the beginning...

data/Dockerfile

@@ -0,0 +1,39 @@
+# syntax=docker/dockerfile:1
+
+FROM ruby:3.4-slim AS deps
+
+WORKDIR /build
+
+RUN apt-get update -qq && \
+    apt-get install -y --no-install-recommends \
+      build-essential \
+      git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY Gemfile Gemfile.lock zephira.gemspec ./
+COPY lib/zephira/version.rb lib/zephira/version.rb
+
+ENV BUNDLE_WITHOUT="development:test"
+
+RUN bundle install --jobs 4
+
+COPY . .
+RUN gem build zephira.gemspec
+
+
+FROM ruby:3.4-slim AS runtime
+
+RUN apt-get update -qq && \
+    apt-get install -y --no-install-recommends \
+      libreadline-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=deps /usr/local/bundle /usr/local/bundle
+COPY --from=deps /build/zephira-*.gem /tmp/
+
+RUN gem install --local --no-document /tmp/zephira-*.gem && \
+    rm -f /tmp/zephira-*.gem
+
+WORKDIR /workspace
+
+CMD ["zephira"]

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,145 @@
+PATH
+  remote: .
+  specs:
+    zephira (0.1.0)
+      faraday (~> 2.0)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      tty-spinner (~> 0.9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.3)
+    fakefs (3.2.1)
+    faraday (2.14.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    hashdiff (1.2.1)
+    io-console (0.8.2)
+    irb (1.17.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.3)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.84.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    standard (1.54.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.84.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    tty-cursor (0.7.1)
+    tty-screen (0.8.2)
+    tty-spinner (0.9.3)
+      tty-cursor (~> 0.7)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  fakefs (~> 3.2)
+  irb (~> 1.17)
+  rspec (~> 3.13.2)
+  simplecov (~> 0.22)
+  standard (~> 1.54)
+  webmock (~> 3.0)
+  zephira!
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,230 @@
+# Zephira
+
+Zephira is a command-line AI coding assistant written in Ruby.
+
+It runs in your terminal, keeps per-project conversation history, calls a pluggable set of tools, and executes inside a Docker sandbox by default so the agent cannot touch the host system unless you opt out. The codebase is small, plugin-based, and intended to be read end-to-end.
+
+## Features
+
+- Interactive terminal chat loop with per-session token-budget tracking and automatic history compaction
+- Built-in slash commands: `/help`, `/about`, `/model`, `/history`, `/compact`, `/clear`, `/bye`
+- Plugin-style tool system — drop a file in `lib/zephira/tools/` and it is auto-loaded:
+  - file I/O: `read_file`, `update_file`, `delete_file`, `list_directory`
+  - search: `code_search` (ripgrep-backed), `web_search` (Brave Search API)
+  - execution: `shell`, `http_request`
+  - persistent memory: `memory_read`, `memory_write`, `memory_list`, `memory_delete`
+- Concurrent execution of read-only tool calls in a single turn (mutating tools still run sequentially in declared order)
+- Pluggable model + backend layer — register a new model by dropping a file in `lib/zephira/models/`; backends bind per model class
+- OpenAI-compatible backend out of the box; structured to add provider-specific backends without forking the core loop
+- Docker sandbox enabled by default; `--dangerously-skip-sandbox` to opt out
+- Persistent session log + conversation history under `.zephira/` in each project
+- ~95% line coverage on a focused RSpec suite
+
+## Installation
+
+Requirements:
+
+- Ruby 3.2+
+- Bundler
+- Docker, if you want sandboxed execution
+
+Install from RubyGems:
+
+```sh
+gem install zephira
+```
+
+Or install locally for development:
+
+```sh
+git clone https://github.com/aarongough/zephira.git
+cd zephira
+bundle install
+```
+
+## Quick start
+
+Start Zephira in the current project directory:
+
+```sh
+zephira
+```
+
+Show CLI help:
+
+```sh
+zephira --help
+```
+
+Print the installed version:
+
+```sh
+zephira --version
+```
+
+To run without Docker sandboxing:
+
+```sh
+zephira --dangerously-skip-sandbox
+```
+
+Warning: skipping the sandbox gives the agent direct access to your real filesystem.
+
+## Configuration
+
+Zephira reads configuration from:
+
+- environment variables
+- `.zephira.yml` in the current project
+- `~/.zephira.yml` in your home directory
+
+Environment variables take precedence.
+
+Example configuration:
+
+```yaml
+ZEPHIRA_API_KEY: "your_api_key_here"
+ZEPHIRA_MODEL: "gpt-4.1-mini"
+ZEPHIRA_BASE_URL: "https://api.openai.com/v1"
+ZEPHIRA_BACKEND: "openai_compatible"
+ZEPHIRA_BASE_IMAGE: "ruby:3.4-slim"
+ZEPHIRA_BRAVE_SEARCH_API_KEY: "your_brave_api_key_here"
+```
+
+## Supported configuration keys
+
+- `ZEPHIRA_API_KEY` — API key for the selected LLM backend
+- `ZEPHIRA_MODEL` — model name to use
+- `ZEPHIRA_BASE_URL` — base URL for OpenAI-compatible APIs
+- `ZEPHIRA_BACKEND` — backend adapter identifier
+- `ZEPHIRA_BASE_IMAGE` — base Docker image for sandbox execution
+- `ZEPHIRA_BRAVE_SEARCH_API_KEY` — required for the web search tool
+- `ZEPHIRA_SANDBOX` — internal/advanced flag to disable sandboxing
+
+## Sandbox behavior
+
+By default, Zephira attempts to run inside Docker for safer execution.
+
+When sandboxing is enabled, Zephira re-executes itself inside a container and mounts your current project into `/workspace`. This gives the agent access to the project while helping isolate it from the host system.
+
+If Docker is unavailable, Zephira exits with an error and explains how to proceed.
+
+You can bypass sandboxing with:
+
+```sh
+zephira --dangerously-skip-sandbox
+```
+
+Use that only if you understand the risks.
+
+## Interactive commands
+
+Inside Zephira, you can use slash commands:
+
+- `/help` — show available commands
+- `/about` — show project information
+- `/model` — list available models
+- `/model set MODEL_NAME` — switch models for the current session
+- `/history` — print conversation history
+- `/compact` — manually compact the conversation history
+- `/clear` — clear the screen
+- `/bye` — exit the session
+
+## Available models
+
+This repository currently includes model definitions for:
+
+- `gpt-4.1`
+- `gpt-4.1-mini`
+- `gpt-5.4`
+- `gpt-5.5`
+- `gpt-o4-mini`
+- `claude-3.5-sonnet`
+- `llama4`
+
+The exact names available in the running app are determined by the model classes in `lib/zephira/models`.
+
+## Built-in tools
+
+Zephira includes tools for:
+
+- `read_file`
+- `update_file`
+- `delete_file`
+- `list_directory`
+- `code_search`
+- `shell`
+- `http_request`
+- `web_search`
+- `memory_write`
+- `memory_read`
+- `memory_list`
+- `memory_delete`
+
+These tools allow the agent to inspect the project, modify files, run commands, query APIs, and maintain lightweight persistent memory.
+
+## Project structure
+
+```text
+exe/                     Executable entrypoint
+lib/zephira/             Core application code
+lib/zephira/models/      Model definitions
+lib/zephira/tools/       Tool implementations
+lib/zephira/commands/    Slash commands
+lib/zephira/completions/ Readline completions
+spec/                    Test suite
+Dockerfile               Sandbox/runtime image
+```
+
+## Development
+
+Install dependencies:
+
+```sh
+bundle install
+```
+
+Run the test suite:
+
+```sh
+bundle exec rspec
+```
+
+Run linting:
+
+```sh
+bundle exec standardrb --fix
+```
+
+## Design goals
+
+Zephira favors:
+
+- clarity over complexity
+- small, readable components
+- hackability and extension
+- realistic terminal-first workflows
+- sandboxed local agent execution
+
+It is best thought of as a lightweight coding assistant and a learning-oriented agent framework, not a full enterprise platform.
+
+## Logging and history
+
+Zephira stores session information under `.zephira/` in the current project directory, including logs and conversation history. This makes sessions project-local and easy to inspect.
+
+## License
+
+Released under the MIT License.
+
+See:
+
+```text
+license.txt
+```
+
+## Author
+
+Aaron Gough
+
+Project home:
+https://github.com/aarongough/zephira

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+# use Standard Ruby style guide for linting
+require "standard/rake"
+
+task lint: :standard
+task default: %i[spec lint]

data/exe/zephira

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "zephira"
+
+Zephira::CLI.new(ARGV)

data/lib/zephira/agent/status.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Agent
+    class Status
+      def initialize(agent)
+        @agent = agent
+      end
+
+      def verbose(msg)
+        return unless @agent.verbose
+        @agent.update_status(msg)
+      end
+
+      def warn(msg)
+        @agent.update_status(Formatter.color(:dark_red, msg))
+      end
+    end
+  end
+end