kward 0.71.0 → 0.72.0

data/doc/usage.md

@@ -12,7 +12,7 @@ cd ~/code/project
 kward
 ```
 
-When running from source, replace `kward` with `ruby lib/main.rb`.
+When running from source, replace `kward` with `ruby lib/main.rb`. See [Getting started](getting-started.md) for install and sign-in.
 
 ## Common workflows
 
@@ -42,6 +42,14 @@ For larger reviews, use interactive mode so Kward can inspect related files:
 Review the current git diff. If something looks risky, inspect the relevant files before recommending changes.
 ```
 
+To review and commit changes interactively, use `/git`:
+
+```text
+/git
+```
+
+It opens a staging overlay where you can stage or unstage files, preview diffs, and write a commit message without leaving Kward.
+
 ### Make a small code change
 
 ```text
@@ -64,6 +72,14 @@ Or run a shell command yourself from the composer by prefixing it with `!`:
 !git status --short
 ```
 
+For several commands, enter the embedded Kward shell:
+
+```text
+/shell
+```
+
+`/shell` opens `ekwsh`, a Kward-native command mode. Kward keeps the tab bar, composer editing, and transcript rendering while each command runs through your configured shell. Built-ins such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, and `exit` maintain shell-mode state between commands. Plain Tab completes built-in command names, configured aliases, executables from `$PATH`, and file paths from the shell's current directory; `cd` completion suggests directories only. `ekwsh` preserves safe ANSI SGR color/style output while stripping terminal-control sequences that could corrupt the TUI, and sets conservative color-friendly environment defaults such as `CLICOLOR=1`, `COLORTERM=truecolor`, and `TERM=xterm-256color` when needed. It does not force color by default; set `FORCE_COLOR`, `CLICOLOR_FORCE`, or command-specific flags such as `--color=always` if you want more aggressive color output. You can set global shell env vars and aliases in `~/.kward/ekwsh.yml`; see [Configuration](configuration.md). It is intended for command output, not full-screen interactive programs such as editors or pagers.
+
 ## Shell commands
 
 Useful shell commands:
@@ -72,10 +88,12 @@ Useful shell commands:
 kward                          # start interactive chat
 kward "Explain this project"   # ask one question and exit
 kward help                     # show commands and examples
+kward version                  # show the installed version
 kward doctor                   # check local setup
 kward login                    # sign in or save credentials
 kward auth status              # show credential status without secrets
 kward sysprompt                # inspect assembled instructions
+kward stats tokens             # export local token telemetry as CSV
 kward rpc                      # start the experimental RPC backend
 ```
 
@@ -88,15 +106,26 @@ kward --working-directory ~/code/project "Summarize this repository"
 
 ## Interactive slash commands
 
-Use slash commands for local actions that should not go to the model:
+Slash commands run local actions in the current session. Most do not send a prompt to the model; exceptions like `/git` and `/workers` orchestrate local flows that may then trigger model work.
 
 | Command | Use it when you want to... |
 | --- | --- |
 | `/login` | sign in or save provider credentials. |
 | `/model` | choose the active model. |
 | `/reasoning` | choose reasoning effort. |
+| `/git` | review uncommitted changes, stage files, and commit. |
+| `/files` | browse project files in a nested tree and open them in the editor. |
+| `/shell` | run workspace commands in the embedded Kward shell. |
+| `/settings` | configure prompt overlays. |
 | `/status` | see session, model, and context status. |
-| `/new` | start a fresh session. |
+| `/new` | start a fresh session in the current tab. |
+| `/tab 2` | switch to tab 2. |
+| `/tab move 1` | move the active tab to position 1. |
+| `/tab move left` | move the active tab one position left. |
+| `/tab move right` | move the active tab one position right. |
+| `/tab close` | close the active tab. |
+| `/tab new` | open a new tab. |
+| `/tab name <label>` | rename the active tab label. |
 | `/sessions` | open the saved sessions picker or continue a previous session by path. |
 | `/resume` | alias for `/sessions`. |
 | `/name <name>` | name or clear the current session. |
@@ -107,13 +136,23 @@ Use slash commands for local actions that should not go to the model:
 | `/copy last` | copy the latest assistant answer. |
 | `/copy transcript` | copy the transcript as Markdown. |
 | `/export notes.md` | write the transcript to a Markdown file. |
-| `/compact [focus]` | summarize older context so a long chat can continue. |
+| `/compact [instructions]` | summarize older context so a long chat can continue. |
 | `/memory ...` | manage opt-in memory. |
 | `/redraw` | fix terminal drawing after resize or glitches. |
+| `/reload` | reload installed plugins. |
+| `/workers` | open the experimental worker pipeline (`new`, `do <task>`, or `list`). |
 | `/exit` | leave Kward. |
 
 Prompt templates and plugins can add more slash commands.
 
+## Prompt history
+
+In interactive mode, Kward keeps prompt history per workspace under `~/.kward/history/`. Press Up/Down to recall previous prompts across restarts.
+
+Press `Ctrl-R` to search history. Type a fuzzy query in the composer, use Up/Down to choose a result from the overlay, then press Enter to place it back in the composer for editing or resubmission. Press Esc or Ctrl-C to cancel the search and restore the draft.
+
+`$path` editor-open commands are also saved after a file opens successfully, using the resolved workspace-relative path.
+
 ## Sessions
 
 Interactive chats are saved as workspace-scoped sessions under:
@@ -149,11 +188,18 @@ One-shot prompts are best for short tasks that do not need session history:
 
 ```bash
 kward "What does this repository do?"
+cat error.log | kward
+```
+
+When stdin and a prompt are both present, Kward runs in filter mode: stdin is the input, the prompt is the instruction, and stdout contains only the transformed result. You can also force this with `--filter` or `--mode filter`.
+
+```bash
 git diff | kward "Review this diff"
-cat error.log | kward "Explain the likely cause"
+echo "Hello" | kward --filter "Translate to German"
+kward --mode filter "Indent this JSON" < unindented.json
 ```
 
-Use `--` when your prompt starts with something that could be parsed as a command or option:
+Use `--mode chat`, `--mode oneshot`, or `--mode filter` to override automatic mode detection. Use `--` when your prompt starts with something that could be parsed as a command or option:
 
 ```bash
 kward -- explain --working-directory
@@ -181,7 +227,7 @@ Important guardrails:
 
 ## Images
 
-If the active model supports images, Kward can attach image paths, Markdown image links, `file://` URLs, or image data URLs pasted into the composer.
+If the active model supports images, Kward can attach image paths, Markdown image links, `file://` URLs, or image data URLs pasted into the composer. Supported formats are GIF, JPEG, PNG, and WebP, up to 20 MB per image.
 
 Use this for tasks such as:
 

data/doc/web-search.md

@@ -36,16 +36,18 @@ Kward should search first, then fetch important pages before relying on them.
 
 ## Network behavior
 
-Web tools are advertised to the model by default. Queries and fetched URLs are sent over the network to the selected provider or target host.
+Web tools are advertised to the model by default. Queries and fetched URLs are sent over the network to the selected provider or target host. See [Configuration](configuration.md) for the full `web_search` config reference including API key storage and the `provider` config setting.
 
 In automatic mode, provider fallback is:
 
 1. Exa API when `EXA_API_KEY` is configured, otherwise keyless Exa MCP.
-2. Perplexity API when configured and model-provider fallback is allowed.
-3. Gemini API with Google Search grounding when configured and model-provider fallback is allowed.
+2. Perplexity API when `PERPLEXITY_API_KEY` is configured and model-provider fallback is allowed.
+3. Gemini API with Google Search grounding when `GEMINI_API_KEY` is configured and model-provider fallback is allowed.
 4. DuckDuckGo HTML search, then bundled public SearXNG instances.
 
-You do not need an API key for basic web search, but keys can improve limits or provider choice.
+You do not need an API key for basic web search, but keys can improve limits or provider choice. The default provider can also be set in config as `web_search.provider`; the tool argument overrides it for a single call.
+
+Search output is capped at 8 KB total, with excerpts up to 300 characters and answer text up to 2,000 characters. HTTP requests use a 10-second timeout.
 
 ## Disable web tools
 
@@ -83,6 +85,10 @@ Arguments:
 - `max_bytes`: default 16384, capped at 131072.
 - `extract`: optional `auto`, `text`, or `markdown`.
 
+In `auto` mode (default), Kward detects HTML content and extracts readable text by stripping scripts, styles, navigation, and forms, preserving headings, paragraphs, lists, code blocks, and blockquotes. Non-HTML content is returned as cleaned text. Use `markdown` to format extracted headings and code blocks as Markdown, or `text` for plain text without formatting.
+
+Fetches follow up to 5 redirects and use a 10-second HTTP timeout.
+
 ### `fetch_raw`
 
 Reads a specific HTTP or HTTPS resource without readability extraction. Use it for JSON, YAML, XML, RSS, OpenAPI specs, and plain text.
@@ -92,3 +98,5 @@ Arguments:
 - `url`
 - `max_bytes`: default 16384, capped at 131072.
 - `accept`: optional HTTP `Accept` header.
+
+Fetches follow up to 5 redirects and use a 10-second HTTP timeout.

data/doc/workspace-tools.md

@@ -12,14 +12,14 @@ Kward normally chooses these tools itself. You do not need to know their exact n
 
 ## Guardrails
 
-Workspace tools use the active workspace as their boundary. File paths are workspace-relative by default, and file tools are guarded so Kward does not edit arbitrary unread files.
+Workspace tools use the active workspace as their boundary. File paths are workspace-relative by default, and file tools are guarded so Kward does not edit arbitrary unread files. Guardrails can be disabled with the `tools.workspace_guardrails` setting — see [Configuration](configuration.md). When disabled, file tools can access paths outside the workspace, but shell commands are unaffected since they already run as your OS user.
 
 Important behavior:
 
 - Existing files must be read in the current conversation before `write_file` or `edit_file` can change them.
-- Reads are bounded to avoid pulling very large files into context by accident.
+- Reads are bounded to avoid pulling very large files into context by accident. Files larger than 256 KB cannot be read or edited. Read output is capped at 50 KB or 2,000 lines, whichever comes first.
 - Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
-- Shell commands run as your operating-system user from the workspace. They are powerful and should be treated like commands you run yourself.
+- Shell commands run as your operating-system user from the workspace. They are powerful and should be treated like commands you run yourself. Command output is capped at 128 KB.
 
 ## Reading the workspace
 
@@ -33,25 +33,55 @@ Arguments:
 
 ### `read_file`
 
-Reads a workspace text file. Output is capped, and Kward can continue with line offsets when it needs more detail.
+Reads a workspace text file. Output is capped, and Kward can continue with line offsets when it needs more detail. The tool also supports explicit context modes so Kward can start cheap and widen only when needed.
 
 Arguments:
 
 - `path`: workspace-relative file path.
 - `offset`: optional 1-indexed start line.
 - `limit`: optional maximum number of lines.
+- `mode`: optional context mode:
+  - `preview`: read a short preview slice, defaulting to 120 lines when `limit` is omitted.
+  - `outline`: return only the source declaration outline.
+  - `range`: read the requested `offset`/`limit` slice.
+  - `full`: read from `offset` until Kward's read caps stop the response.
+- `max_bytes`: optional per-call byte budget, capped by Kward's workspace read limit.
 
 A successful read marks the resolved file path as read for the conversation, allowing later edits to that file.
 
+When called without `offset`, `limit`, or `mode` on a file that exceeds 2,000 lines or 50 KB, Kward returns a structure outline (classes, modules, methods) plus the first 120 lines instead of truncating blindly. This helps identify relevant entry points before requesting specific line ranges.
+
+Binary files (detected by null bytes) return an error instead of content.
+
+### `context_budget_stats`
+
+Returns approximate context-budget savings for the current active conversation since it was opened in this process. The report compares each raw tool result size with the model-facing result after compaction or duplicate replacement, includes per-tool totals, and estimates saved tokens using roughly four bytes per token.
+
+Arguments: none.
+
+These numbers are intentionally approximate runtime stats. They are useful for seeing whether Kward's budgeting is helping the current conversation, not for billing, and they are not reconstructed when a saved session is resumed.
+
+### `context_for_task`
+
+Builds a compact, task-shaped context bundle from likely workspace files. It ranks files by task terms, includes source outlines, and adds short matching excerpts while respecting an approximate byte budget. This is intentionally lightweight: it does not maintain a persistent index or semantic graph.
+
+Arguments:
+
+- `task`: required task or question to gather context for.
+- `paths`: optional files or directories to focus. Defaults to the workspace root.
+- `budget`: optional approximate byte budget, default 4,000 and capped at 20,000.
+
+Use this when Kward needs orientation for a bug, review, implementation, or explanation before deciding which exact file ranges to read.
+
 ### `summarize_file_structure`
 
-Returns a compact outline of classes, modules, methods, and functions in a source file. Kward uses it when a file may be too large to read fully at first.
+Returns a compact outline of recognizable declarations in a source file, including line ranges and declaration kind where Kward can infer them. Kward uses it when a file may be too large to read fully at first.
 
 Arguments:
 
 - `path`: workspace-relative source file path.
 
-This tool saves tokens by letting Kward identify relevant entry points before requesting exact line ranges with `read_file`.
+This tool saves tokens by letting Kward identify relevant entry points before requesting exact line ranges with `read_file`. The outline is capped at 80 entries and recognizes common Ruby, JavaScript/TypeScript, Go, Rust, Java, and C#-style declarations with lightweight pattern matching rather than a full parser. Binary files (detected by null bytes) return an error instead of content.
 
 ## Changing files
 
@@ -66,6 +96,8 @@ Arguments:
 
 Use full writes when replacing generated content or creating a new file. For small edits to existing files, Kward should usually prefer `edit_file`.
 
+The result includes a unified diff of the changes, capped at 8 KB with a summary of additions and deletions when truncated.
+
 ### `edit_file`
 
 Applies one or more exact replacements to a file that has already been read.
@@ -77,7 +109,9 @@ Arguments:
   - `old_text`: unique exact text to replace.
   - `new_text`: replacement text.
 
-Each `old_text` must match exactly once, and replacements must not overlap. This keeps edits deterministic and avoids broad fuzzy rewriting.
+Each `old_text` must match exactly once, and replacements must not overlap. This keeps edits deterministic and avoids broad fuzzy rewriting. Empty `old_text`, multiple matches, and no-op edits (where the result is identical) are all rejected with an error.
+
+The result includes a unified diff of the changes, capped at 8 KB with a summary of additions and deletions when truncated.
 
 ## Running commands
 
@@ -90,16 +124,21 @@ Arguments:
 - `command`: command to run.
 - `timeout_seconds`: optional timeout, default 30 seconds.
 
-Kward uses shell commands for tests, linters, build checks, and simple repository inspection. Command output is bounded and may be compacted before it is sent back into model context, while the original output remains available in the session record.
+Kward uses shell commands for tests, linters, build checks, and simple repository inspection. Command output is bounded at 128 KB and may be compacted before it is sent back into model context, while the original output remains available in the session record.
+
+The output format is `Exit status: N` followed by `STDOUT:` and `STDERR:` sections. On timeout, Kward sends SIGTERM then SIGKILL after 0.2 seconds and returns a timeout error. Commands support cooperative cancellation when the session is cancelled.
 
 ## Token behavior
 
 Workspace tools are intentionally incremental:
 
 1. list directories to find likely files,
-2. summarize large source files before reading everything,
-3. read focused line ranges,
-4. make exact edits,
-5. run focused verification commands.
+2. use `read_file` with `mode: "outline"` or `summarize_file_structure` before reading everything,
+3. read focused line ranges with `mode: "range"`, `offset`, `limit`, and optional `max_bytes`,
+4. widen to `mode: "full"` only when focused context is insufficient,
+5. make exact edits,
+6. run focused verification commands.
 
 This keeps the model's context window focused on relevant evidence instead of flooding it with entire repositories or long command output.
+
+For details on how tool outputs are compacted, deduplicated, and retrieved, see [Agent tools](agent-tools.md).

data/examples/plugins/space_invaders.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+# Space Invaders — a full classic arcade game built as a Kward interactive
+# plugin command.
+#
+# Install: copy this file to ~/.kward/plugins/ and run `/invaders` in the
+# Kward TUI.
+#
+# Controls:
+#   ←/→  Move
+#   Space  Fire
+#   Q / Esc  Quit
+#   Ctrl+C  Force quit (handled by Kward)
+#
+# The game renders colored sprites and particle-burst explosions inside the
+# composer canvas region using the interactive mode API.
+
+Kward.plugin do |plugin|
+  plugin.interactive_command "invaders", rows: 18, fps: 30, description: "Space Invaders arcade game" do |ui, ctx|
+    game = SpaceInvadersGame.new(width: ui.width, height: ui.height)
+    ui.on_tick { |ui| game.tick(ui) }
+  end
+end
+
+# rubocop:disable Metrics/ClassLength, Metrics/MethodLength
+class SpaceInvadersGame
+  PLAYER_CHAR = "▲"
+  PLAYER_COLOR = :cyan
+  BULLET_CHAR = "│"
+  BULLET_COLOR = :yellow
+  BOMB_CHAR = "V"
+  BOMB_COLOR = :magenta
+  SCORE_LABEL = "Score"
+  LIVES_LABEL = "Lives"
+
+  INVADER_ROWS = [
+    { char: "M", color: :red,    points: 30 },
+    { char: "M", color: :red,    points: 30 },
+    { char: "W", color: :yellow, points: 20 },
+    { char: "W", color: :yellow, points: 20 },
+    { char: "A", color: :green,  points: 10 }
+  ].freeze
+
+  PARTICLE_CHARS = %w[* + . o].freeze
+  PARTICLE_COLORS = %i[red yellow].freeze
+  PARTICLE_LIFE = 6
+
+  MOVE_EVERY = 12
+  BULLET_SPEED = 2
+  BOMB_SPEED = 1
+  MAX_BULLETS = 3
+  FIRE_COOLDOWN = 8
+  BOMB_CHANCE = 0.015
+
+  def initialize(width:, height:)
+    @width = width
+    @height = height
+    @phase = :playing
+    @tick_count = 0
+    @score = 0
+    @lives = 3
+    @wave = 1
+    @fire_cooldown = 0
+    @invader_dir = 1
+    @invaders = []
+    @bullets = []
+    @bombs = []
+    @explosions = []
+    @message_timer = 0
+    spawn_invaders
+    place_player
+  end
+
+  def tick(ui)
+    drain_keys(ui)
+    case @phase
+    when :playing
+      update_playing
+      render_playing(ui)
+    when :game_over, :won
+      update_message_phase
+      render_message(ui)
+    end
+    ui.render
+  end
+
+  private
+
+  def drain_keys(ui)
+    while (key = ui.poll_key)
+      case key
+      when :escape, "q", "Q"
+        ui.exit
+      when :left
+        @player_col -= 1 if @phase == :playing
+      when :right
+        @player_col += 1 if @phase == :playing
+      when :space
+        fire_bullet if @phase == :playing
+      when :return, :enter
+        restart if @phase != :playing
+      end
+    end
+  end
+
+  def place_player
+    @player_col = @width / 2
+    @player_row = @height - 2
+  end
+
+  # ---- Invader spawning ----
+
+  def spawn_invaders
+    @invaders = []
+    rows = INVADER_ROWS.length
+    cols = [(@width - 4) / 4, 6].min
+    cols = [cols, 3].max
+    start_row = 2
+    start_col = (@width - cols * 4) / 2
+    start_col = [start_col, 1].max
+
+    rows.times do |row|
+      config = INVADER_ROWS[row]
+      cols.times do |col|
+        @invaders << {
+          row: start_row + row,
+          col: start_col + col * 4,
+          char: config[:char],
+          color: config[:color],
+          points: config[:points],
+          alive: true
+        }
+      end
+    end
+    @invader_dir = 1
+  end
+
+  # ---- Playing phase updates ----
+
+  def update_playing
+    @tick_count += 1
+    @fire_cooldown = [@fire_cooldown - 1, 0].max if @fire_cooldown.positive?
+
+    move_invaders if (@tick_count % move_interval).zero?
+    move_bullets
+    move_bombs
+    maybe_drop_bomb
+    update_explosions
+    check_collisions
+    check_win_lose
+  end
+
+  def move_interval
+    alive = @invaders.count { |inv| inv[:alive] }
+    total = @invaders.length
+    return MOVE_EVERY if total.zero?
+
+    speedup = ((total - alive) * MOVE_EVERY) / (total * 2)
+    [MOVE_EVERY - speedup, 2].max
+  end
+
+  def move_invaders
+    living = @invaders.select { |inv| inv[:alive] }
+    return if living.empty?
+
+    min_col = living.map { |inv| inv[:col] }.min
+    max_col = living.map { |inv| inv[:col] }.max
+
+    if @invader_dir.positive? && max_col >= @width - 2
+      @invader_dir = -1
+      @invaders.each { |inv| inv[:row] += 1 if inv[:alive] }
+    elsif @invader_dir.negative? && min_col <= 1
+      @invader_dir = 1
+      @invaders.each { |inv| inv[:row] += 1 if inv[:alive] }
+    else
+      @invaders.each { |inv| inv[:col] += @invader_dir if inv[:alive] }
+    end
+  end
+
+  def fire_bullet
+    return if @bullets.length >= MAX_BULLETS
+    return if @fire_cooldown.positive?
+
+    @bullets << { row: @player_row - 1, col: @player_col }
+    @fire_cooldown = FIRE_COOLDOWN
+  end
+
+  def move_bullets
+    @bullets.each { |b| b[:row] -= BULLET_SPEED }
+    @bullets.reject! { |b| b[:row] < 0 }
+  end
+
+  def move_bombs
+    @bombs.each { |b| b[:row] += BOMB_SPEED }
+    @bombs.reject! { |b| b[:row] >= @height }
+  end
+
+  def maybe_drop_bomb
+    return if rand > BOMB_CHANCE
+
+    living = @invaders.select { |inv| inv[:alive] }
+    return if living.empty?
+
+    # Drop from a random bottom-most invader per column
+    columns = living.group_by { |inv| inv[:col] }
+    col, invaders = columns.min_by { rand }
+    return unless invaders
+
+    bottom = invaders.max_by { |inv| inv[:row] }
+    @bombs << { row: bottom[:row] + 1, col: bottom[:col] } if bottom
+  end
+
+  # ---- Explosions ----
+
+  def spawn_explosion(row, col, color = :red)
+    PARTICLE_LIFE.times do |i|
+      angle = (i * 360 / PARTICLE_LIFE) * Math::PI / 180
+      dx = (Math.cos(angle) * (i + 1)).round
+      dy = (Math.sin(angle) * (i + 1)).round
+      @explosions << {
+        row: row + dy,
+        col: col + dx,
+        char: PARTICLE_CHARS[i % PARTICLE_CHARS.length],
+        color: PARTICLE_COLORS[i % PARTICLE_COLORS.length],
+        life: PARTICLE_LIFE
+      }
+    end
+  end
+
+  def update_explosions
+    @explosions.each { |e| e[:life] -= 1 }
+    @explosions.reject! { |e| e[:life] <= 0 }
+  end
+
+  # ---- Collisions ----
+
+  def check_collisions
+    check_bullet_invader_hits
+    check_bomb_player_hits
+  end
+
+  def check_bullet_invader_hits
+    @bullets.reject! do |bullet|
+      hit = @invaders.find { |inv| inv[:alive] && inv[:row] == bullet[:row] && inv[:col] == bullet[:col] }
+      next false unless hit
+
+      hit[:alive] = false
+      @score += hit[:points]
+      spawn_explosion(hit[:row], hit[:col], hit[:color])
+      true
+    end
+  end
+
+  def check_bomb_player_hits
+    @bombs.reject! do |bomb|
+      hit = bomb[:row] == @player_row && bomb[:col] == @player_col
+      next false unless hit
+
+      @lives -= 1
+      spawn_explosion(@player_row, @player_col, :cyan)
+      @phase = :game_over if @lives <= 0
+      true
+    end
+  end
+
+  def check_win_lose
+    return unless @phase == :playing
+
+    @phase = :won if @invaders.none? { |inv| inv[:alive] }
+
+    return unless @invaders.any? { |inv| inv[:alive] && inv[:row] >= @player_row }
+
+    @phase = :game_over
+    spawn_explosion(@player_row, @player_col, :cyan)
+  end
+
+  # ---- Message phase ----
+
+  def update_message_phase
+    @message_timer += 1
+  end
+
+  def restart
+    @score = 0
+    @lives = 3
+    @wave = 1
+    @tick_count = 0
+    @bullets.clear
+    @bombs.clear
+    @explosions.clear
+    @fire_cooldown = 0
+    @invader_dir = 1
+    spawn_invaders
+    place_player
+    @phase = :playing
+    @message_timer = 0
+  end
+
+  # ---- Rendering ----
+
+  def render_playing(ui)
+    ui.clear_frame
+
+    render_hud(ui)
+    render_invaders(ui)
+    render_bullets(ui)
+    render_bombs(ui)
+    render_explosions(ui)
+    ui.put(@player_row, @player_col, PLAYER_CHAR, PLAYER_COLOR)
+  end
+
+  def render_hud(ui)
+    score_text = "#{SCORE_LABEL}: #{@score}"
+    lives_text = "#{LIVES_LABEL}: #{@lives}"
+    wave_text = "Wave: #{@wave}"
+
+    score_text.chars.each_with_index do |char, i|
+      ui.put(0, i, char, :green)
+    end
+    lives_col = @width - lives_text.length
+    lives_text.chars.each_with_index do |char, i|
+      ui.put(0, lives_col + i, char, :cyan)
+    end
+    wave_col = (@width - wave_text.length) / 2
+    wave_text.chars.each_with_index do |char, i|
+      ui.put(0, wave_col + i, char, :gray)
+    end
+  end
+
+  def render_invaders(ui)
+    @invaders.each do |inv|
+      next unless inv[:alive]
+
+      ui.put(inv[:row], inv[:col], inv[:char], inv[:color])
+    end
+  end
+
+  def render_bullets(ui)
+    @bullets.each { |b| ui.put(b[:row], b[:col], BULLET_CHAR, BULLET_COLOR) }
+  end
+
+  def render_bombs(ui)
+    @bombs.each { |b| ui.put(b[:row], b[:col], BOMB_CHAR, BOMB_COLOR) }
+  end
+
+  def render_explosions(ui)
+    @explosions.each do |e|
+      ui.put(e[:row], e[:col], e[:char], e[:color])
+    end
+  end
+
+  def render_message(ui)
+    ui.clear_frame
+    render_invaders(ui)
+    render_explosions(ui)
+
+    if @phase == :won
+      message = "YOU WIN!"
+      color = :green
+    else
+      message = "GAME OVER"
+      color = :red
+    end
+
+    center_text(ui, @height / 2, message, color)
+    center_text(ui, @height / 2 + 2, "Score: #{@score}", :yellow)
+    center_text(ui, @height / 2 + 4, "Enter: restart  Q: quit", :gray)
+  end
+
+  def center_text(ui, row, text, color)
+    col = (@width - text.length) / 2
+    text.chars.each_with_index do |char, i|
+      ui.put(row, col + i, char, color)
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength, Metrics/MethodLength

data/lib/kward/agent.rb

@@ -31,7 +31,7 @@ module Kward
       @telemetry_logger = telemetry_logger
     end
 
-    attr_reader :conversation
+    attr_reader :conversation, :tool_registry
 
     # Adds a user message, compacts context when needed, and runs the turn.
     #