kward 0.66.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d6d8b5577dbec359eb683a0ce26cb87276b334b2d6346670df0338c9f10b123f
+  data.tar.gz: abbd42bade9aed052e52b0e5c9ef6f9e560b56c35558346736d3963bdb34fc76
+SHA512:
+  metadata.gz: 81c6bf970a1dd702e30ee6481feaa57fa11457fca292d17dd0f609c2e37981f9cf72d1e610d2f354a77f7093a3e21fd16b67fea03a54ad30e69c560f72081343
+  data.tar.gz: daa54b6f0db9025b84ad14393654dbce127083f307ca67f0612100e0b015a499ab9f06a5cf413b80ea7e4d5f9f8386b11ae175a4d610f4e2fc90ab3817bd5390

data/.yardopts

@@ -0,0 +1,9 @@
+--readme README.md
+--output-dir _yardoc
+--markup markdown
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE
+doc/**/*.md

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to Kward will be documented in this file.
+
+## Unreleased
+
+- No changes yet.
+
+## 0.66.0 - 2026-06-12 - Codename: Order
+
+- Initial public release.
+- Prepare RubyGems packaging for the initial public release.

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest"
+gem "rake"
+gem "rdoc"
+gem "yard"

data/Gemfile.lock

@@ -0,0 +1,90 @@
+PATH
+  remote: .
+  specs:
+    kward (0.66.0)
+      base64
+      nokogiri
+      tiktoken_ruby
+      tty-cursor
+      tty-prompt
+      tty-reader
+      tty-screen
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.3.0)
+    date (3.5.1)
+    drb (2.2.3)
+    erb (6.0.4)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    nokogiri (1.19.3-arm64-darwin)
+      racc (~> 1.4)
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    prism (1.9.0)
+    psych (5.4.0)
+      date
+      stringio
+    racc (1.8.1)
+    rake (13.3.1)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    stringio (3.2.0)
+    tiktoken_ruby (0.0.16-arm64-darwin)
+    tsort (0.2.0)
+    tty-color (0.6.0)
+    tty-cursor (0.7.1)
+    tty-prompt (0.23.1)
+      pastel (~> 0.8)
+      tty-reader (~> 0.8)
+    tty-reader (0.9.0)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      wisper (~> 2.0)
+    tty-screen (0.8.2)
+    wisper (2.0.1)
+    yard (0.9.44)
+
+PLATFORMS
+  arm64-darwin
+  arm64-darwin-25
+
+DEPENDENCIES
+  kward!
+  minitest
+  rake
+  rdoc
+  yard
+
+CHECKSUMS
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
+  kward (0.66.0)
+  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
+  nokogiri (1.19.3-arm64-darwin) sha256=71b9bd424b1b7abc18b05052a1a3cfd3627abdca62be280854cc411791357e42
+  pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  psych (5.4.0) sha256=14f72d69a611af663d7d70e4a7b67d9eb1f3ae9f8d916b478961d5a0075ba5b7
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  tiktoken_ruby (0.0.16-arm64-darwin) sha256=3da6fe850bf920d08c7eb736673f50bc9d08e8f2e17d34904ad3185a73fc9da7
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  tty-color (0.6.0) sha256=6f9c37ca3a4e2367fb2e6d09722762647d6f455c111f05b59f35730eeb24332a
+  tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48
+  tty-prompt (0.23.1) sha256=fcdbce905238993f27eecfdf67597a636bc839d92192f6a0eef22b8166449ec8
+  tty-reader (0.9.0) sha256=c62972c985c0b1566f0e56743b6a7882f979d3dc32ff491ed490a076f899c2b1
+  tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
+  wisper (2.0.1) sha256=ce17bc5c3a166f241a2e6613848b025c8146fce2defba505920c1d1f3f88fae6
+  yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
+
+BUNDLED WITH
+  4.0.6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kai Wood
+
+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,101 @@
+# Kward
+
+Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run confirmed shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
+
+It currently supports the OpenAI/ChatGPT Codex backend, OpenRouter, and experimental Copilot provider support.
+
+## Install
+
+Kward is being prepared for a RubyGems release. Once published, install it with:
+
+```bash
+gem install kward
+```
+
+Optionally install the starter pack after installation:
+
+```bash
+kward --install-starter-pack
+```
+
+This downloads Kward's default prompts and base `AGENTS.md` into your config directory. It is useful for a first setup, but safe to skip if you prefer to create your own instructions. Existing files are left untouched.
+
+Then start Kward and sign in when needed:
+
+```bash
+kward                          # start an interactive chat
+/login                         # from inside Kward: sign in or save provider credentials
+kward login                    # from your shell: sign in or save provider credentials
+kward "Explain this project"   # run one prompt and exit
+```
+
+See [Authentication](doc/authentication.md) for more details about sign-in options and provider credentials.
+
+## Run from source
+
+If you are working from a checkout:
+
+```bash
+bundle install
+ruby lib/main.rb login                    # sign in or save provider credentials
+ruby lib/main.rb                          # start an interactive chat
+ruby lib/main.rb "Explain this project"   # run one prompt and exit
+```
+
+You can also use the executable directly after installing dependencies:
+
+```bash
+exe/kward
+```
+
+## What Kward can do
+
+- Keep a multi-turn coding conversation in your terminal.
+- Read, write, and edit workspace files with confirmation before changes.
+- Run shell commands after confirmation.
+- Search the live web and inspect cached public GitHub repositories.
+- Save, resume, clone, compact, and export sessions.
+- Extend the Agent with trusted Ruby plugins for custom commands, footer UI, prompt context, and transcript-event observers.
+- Use optional memory, personas, prompt templates, and skills.
+- Serve an experimental JSON-RPC backend for UI clients.
+
+## Documentation
+
+Start here:
+
+- [Getting started](doc/getting-started.md): first run, authentication choices, and basic commands.
+- [Usage](doc/usage.md): interactive chat, slash commands, sessions, tools, images, and Pan mode.
+- [Configuration](doc/configuration.md): config files, providers, models, web search, logging, and color output.
+- [Authentication](doc/authentication.md): OpenAI OAuth, OpenRouter API keys, and Copilot/GitHub setup.
+
+Feature guides:
+
+- [Memory](doc/memory.md): opt-in core, soft, and session memory.
+- [Extensibility](doc/extensibility.md): `AGENTS.md`, personas, skills, and prompt templates.
+- [Plugins](doc/plugins.md): trusted Ruby plugins for commands, footer UI, prompt context, transcript events, and RPC clients.
+- [Web search](doc/web-search.md): live search providers and network behavior.
+- [Code search](doc/code-search.md): package lookup, GitHub repository cache, and external source reading.
+
+Advanced/reference:
+
+- [RPC protocol](doc/rpc.md): experimental JSON-RPC backend mode for UI clients.
+- [Releasing](doc/releasing.md): release checklist for RubyGems publishing.
+
+## Run tests
+
+```bash
+bundle exec rake test
+```
+
+Equivalent direct command:
+
+```bash
+ruby -Itest -e 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'
+```
+
+## Generate API documentation
+
+```bash
+bundle exec rake rdoc
+bundle exec yard doc
+```

data/Rakefile

@@ -0,0 +1,20 @@
+require "rdoc/task"
+require "yard"
+require "yard/rake/yardoc_task"
+
+task default: :test
+
+task :test do
+  ruby "-Itest", "-e", 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE", "doc/**/*.md", "lib/**/*.rb")
+end
+
+YARD::Rake::YardocTask.new do |yard|
+  yard.files = ["lib/**/*.rb", "-", "README.md", "CHANGELOG.md", "LICENSE", "doc/**/*.md"]
+  yard.options = ["--readme", "README.md", "--output-dir", "_yardoc", "--markup", "markdown"]
+end

data/doc/authentication.md

@@ -0,0 +1,105 @@
+# Authentication
+
+Kward needs credentials for a model provider before it can answer prompts. The easiest path is to start Kward and run `/login`.
+
+Kward supports:
+
+- OpenAI/ChatGPT OAuth for the Codex backend.
+- OpenRouter API keys.
+- GitHub OAuth or `COPILOT_GITHUB_TOKEN` for experimental Copilot provider support.
+
+If you installed the gem, use `kward` in the examples below. When running from source, use `ruby lib/main.rb` instead.
+
+## Quick login
+
+Inside an interactive session:
+
+```text
+/login
+```
+
+Kward opens a provider picker and saves the selected credentials.
+
+From your shell, you can also run:
+
+```bash
+kward login              # OpenAI/ChatGPT OAuth
+kward login openrouter   # save an OpenRouter API key
+kward login github       # GitHub OAuth for experimental Copilot support
+```
+
+## OpenAI OAuth
+
+OpenAI OAuth is the default provider path when credentials are available. It uses your ChatGPT account and sends requests to the ChatGPT/Codex backend (`chatgpt.com/backend-api/codex/responses`), not the OpenAI Platform API.
+
+To start the browser login from your shell:
+
+```bash
+kward login
+```
+
+In an interactive session, run `/login` and choose OpenAI.
+
+Complete the browser redirect flow. Tokens are saved to:
+
+```text
+~/.kward/auth.json
+```
+
+The auth file is written with file mode `0600`.
+
+OpenAI OAuth requires an OAuth client ID in `~/.kward/config.json`:
+
+```json
+{
+  "openai_oauth_client_id": "your-client-id"
+}
+```
+
+If it is missing, Kward tells you which config file to update.
+
+## OpenRouter API key
+
+OpenRouter uses an API key rather than OAuth. To save it from your shell:
+
+```bash
+kward login openrouter
+```
+
+In an interactive session, run `/login` and choose OpenRouter.
+
+Kward saves the key as `openrouter_api_key` in `~/.kward/config.json`. You can also set `OPENROUTER_API_KEY` for a single run without saving it.
+
+## GitHub OAuth for Copilot provider support
+
+Kward can use a GitHub token for experimental Copilot provider support.
+
+The GitHub device flow uses a built-in default client ID unless you set `GITHUB_OAUTH_CLIENT_ID` or add `github_oauth_client_id` to `~/.kward/config.json`. To log in:
+
+```bash
+kward login github
+```
+
+Tokens are saved to:
+
+```text
+~/.kward/github_auth.json
+```
+
+The auth file is written with file mode `0600`.
+
+You can also run `/login` in an interactive session and choose GitHub, or provide `COPILOT_GITHUB_TOKEN` for a single run.
+
+Important: Kward's Copilot provider follows Pi Agent's direct HTTPS approach. It exchanges the GitHub OAuth token for a Copilot internal token and sends chat requests to the Copilot proxy API. It does not use the official Copilot CLI or SDK runtime.
+
+## Fallback and provider selection
+
+Credential priority is provider-aware:
+
+- OpenAI OAuth is used by default after login, even when `OPENROUTER_API_KEY` or `openrouter_api_key` is also present.
+- `OPENAI_ACCESS_TOKEN` can be used as an OpenAI environment fallback.
+- `OPENROUTER_API_KEY` is a fallback only when no OpenAI OAuth/access token exists.
+- `COPILOT_GITHUB_TOKEN` can be used as a Copilot environment fallback.
+- If `provider` in config or `KWARD_PROVIDER` in the environment is set to `codex`, `openrouter`, or `copilot`, Kward uses that provider and does not fall through to another provider.
+
+See [Configuration](configuration.md) for model and provider settings.

data/doc/code-search.md

@@ -0,0 +1,56 @@
+# Code search
+
+Kward exposes a `code_search` tool so the agent can inspect public open-source code for implementation guidance.
+
+Use code search when you want Kward to learn from real packages before changing your project. It is useful for checking library APIs, finding examples, comparing implementation patterns, or understanding how another project solved a similar problem.
+
+Example prompts:
+
+```text
+Look up how tty-prompt handles key bindings before changing our composer.
+Find examples of Faraday retry middleware usage.
+Inspect how Rails structures this kind of generator test.
+```
+
+The tool can:
+
+- look up packages from RubyGems, npm, PyPI, crates.io, and Go package documentation
+- find public GitHub source repositories from package metadata
+- fall back to GitHub repository search when registry metadata has no source URL
+- clone public GitHub repositories into Kward's cache
+- search cached repository files and return bounded snippets with paths and line numbers
+- read bounded line ranges from cached repository files
+- list, refresh, and clear cached repositories
+
+## Cache
+
+Repositories are cloned under:
+
+```text
+~/.kward/cache/code_search
+```
+
+If `KWARD_CONFIG_PATH` points at another config location, the cache is stored next to that config directory under `cache/code_search`.
+
+The tool keeps cloned repositories outside the current workspace. It uses safe cache keys derived from GitHub `owner/name` identifiers and rejects absolute paths or path traversal when reading files.
+
+## GitHub access
+
+`code_search` uses live network access and the local `git` executable. GitHub authentication is optional. If either `GITHUB_TOKEN` or `GH_TOKEN` is set, the token is sent to GitHub API requests. Without a token, GitHub requests are unauthenticated and may hit lower rate limits.
+
+Tokens are not included in tool output.
+
+## Actions
+
+The tool has one schema with an `action` parameter:
+
+- `package_search` - find package metadata and likely source repository
+- `github_search` - search public GitHub repositories
+- `repo_clone` - clone a GitHub repository into cache if needed
+- `repo_search` - search cached repository files for text
+- `repo_read` - read a bounded line range from a cached repository file
+- `list_cache` - list cached repositories
+- `refresh_cache` - fetch updates for a cached repository
+- `clear_cache` - remove one cached repository
+
+Search and read output is bounded to avoid loading excessive external source into context. Oversized and binary files are skipped.