kward 0.85.0 → 0.86.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +130 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +3 -3
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +11 -0
  8. data/doc/api.md +4 -1
  9. data/doc/composer.md +4 -3
  10. data/doc/configuration.md +60 -11
  11. data/doc/extensibility.md +2 -0
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +1 -1
  14. data/doc/memory.md +1 -1
  15. data/doc/plugins.md +40 -5
  16. data/doc/providers.md +10 -4
  17. data/doc/rpc.md +125 -7
  18. data/doc/session-management.md +36 -1
  19. data/doc/shell.md +643 -27
  20. data/doc/tabs.md +2 -1
  21. data/doc/troubleshooting.md +1 -1
  22. data/doc/usage.md +21 -11
  23. data/examples/plugins/openrouter_proxy/README.md +103 -0
  24. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  25. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  26. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  27. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  28. data/examples/plugins/space_invaders.rb +0 -1
  29. data/exe/kward +2 -2
  30. data/exe/kwsh +7 -0
  31. data/kward.gemspec +3 -1
  32. data/lib/kward/agent.rb +43 -9
  33. data/lib/kward/cli/commands.rb +41 -11
  34. data/lib/kward/cli/interactive_turn.rb +10 -0
  35. data/lib/kward/cli/plugins.rb +5 -1
  36. data/lib/kward/cli/prompt_interface.rb +4 -1
  37. data/lib/kward/cli/rendering.rb +21 -28
  38. data/lib/kward/cli/runtime_helpers.rb +52 -34
  39. data/lib/kward/cli/settings/model.rb +1 -12
  40. data/lib/kward/cli/tabs.rb +91 -18
  41. data/lib/kward/cli/tool_summaries.rb +2 -0
  42. data/lib/kward/cli/transcript_formatter.rb +3 -10
  43. data/lib/kward/cli/worktrees.rb +1 -0
  44. data/lib/kward/cli.rb +56 -7
  45. data/lib/kward/config/core.rb +16 -5
  46. data/lib/kward/config/extensions.rb +3 -0
  47. data/lib/kward/config/paths.rb +11 -0
  48. data/lib/kward/config/settings.rb +7 -0
  49. data/lib/kward/conversation.rb +11 -1
  50. data/lib/kward/entrypoint.rb +14 -0
  51. data/lib/kward/events.rb +2 -0
  52. data/lib/kward/generated_images.rb +237 -0
  53. data/lib/kward/model/catalog.rb +6 -3
  54. data/lib/kward/model/client.rb +105 -36
  55. data/lib/kward/model/codex_images.rb +83 -0
  56. data/lib/kward/model/copilot_models.rb +8 -4
  57. data/lib/kward/model/model_info.rb +27 -9
  58. data/lib/kward/model/openrouter_model_cache.rb +4 -2
  59. data/lib/kward/model/payloads.rb +6 -5
  60. data/lib/kward/model/sources.rb +3 -1
  61. data/lib/kward/model/stream_parser.rb +4 -7
  62. data/lib/kward/pan/index.html.erb +8 -1
  63. data/lib/kward/pan/server.rb +13 -1
  64. data/lib/kward/plugins/codex_responses.rb +73 -0
  65. data/lib/kward/plugins/host.rb +16 -0
  66. data/lib/kward/plugins/http_server.rb +83 -0
  67. data/lib/kward/plugins/registry.rb +39 -0
  68. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  69. data/lib/kward/prompt_interface/composer_renderer.rb +159 -72
  70. data/lib/kward/prompt_interface/editor/controller.rb +1 -1
  71. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  72. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  73. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  74. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  75. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  76. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  77. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  78. data/lib/kward/prompt_interface/layout.rb +11 -1
  79. data/lib/kward/prompt_interface/overlay_renderer.rb +25 -8
  80. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  81. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  82. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  83. data/lib/kward/prompt_interface/runtime_state.rb +31 -9
  84. data/lib/kward/prompt_interface/screen.rb +24 -21
  85. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  86. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  87. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  88. data/lib/kward/prompt_interface.rb +109 -39
  89. data/lib/kward/prompts.rb +7 -1
  90. data/lib/kward/pty/adaptive_output_sink.rb +38 -4
  91. data/lib/kward/pty/interactive_runner.rb +20 -28
  92. data/lib/kward/pty/transcript_normalizer.rb +65 -21
  93. data/lib/kward/rpc/config_manager.rb +3 -0
  94. data/lib/kward/rpc/server.rb +27 -5
  95. data/lib/kward/rpc/session_manager.rb +62 -17
  96. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  97. data/lib/kward/sessions/store.rb +30 -3
  98. data/lib/kward/shell/kwsh.rb +27 -7
  99. data/lib/kward/shell/kwshrc.rb +11 -2
  100. data/lib/kward/shell/native_arithmetic.rb +255 -0
  101. data/lib/kward/shell/native_arrays.rb +102 -0
  102. data/lib/kward/shell/native_braces.rb +96 -0
  103. data/lib/kward/shell/native_builtins.rb +476 -0
  104. data/lib/kward/shell/native_completion.rb +169 -0
  105. data/lib/kward/shell/native_condition.rb +75 -0
  106. data/lib/kward/shell/native_directory.rb +116 -0
  107. data/lib/kward/shell/native_exec_state.rb +73 -0
  108. data/lib/kward/shell/native_expansion.rb +252 -0
  109. data/lib/kward/shell/native_fields.rb +62 -0
  110. data/lib/kward/shell/native_glob.rb +96 -0
  111. data/lib/kward/shell/native_history.rb +242 -0
  112. data/lib/kward/shell/native_interactive.rb +164 -0
  113. data/lib/kward/shell/native_invocation.rb +42 -0
  114. data/lib/kward/shell/native_jobs.rb +250 -0
  115. data/lib/kward/shell/native_line_editor.rb +382 -0
  116. data/lib/kward/shell/native_line_terminal.rb +286 -0
  117. data/lib/kward/shell/native_locale.rb +109 -0
  118. data/lib/kward/shell/native_locals.rb +57 -0
  119. data/lib/kward/shell/native_pattern.rb +200 -0
  120. data/lib/kward/shell/native_process.rb +279 -0
  121. data/lib/kward/shell/native_program.rb +40 -0
  122. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  123. data/lib/kward/shell/native_prompt_format.rb +89 -0
  124. data/lib/kward/shell/native_runtime.rb +964 -0
  125. data/lib/kward/shell/native_substitution.rb +110 -0
  126. data/lib/kward/shell/native_syntax.rb +946 -0
  127. data/lib/kward/shell/native_traps.rb +196 -0
  128. data/lib/kward/shell/native_vi.rb +407 -0
  129. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  130. data/lib/kward/shell/native_worker.rb +82 -0
  131. data/lib/kward/shell/persistent_session.rb +184 -190
  132. data/lib/kward/shell/prompt.rb +14 -0
  133. data/lib/kward/shell/prompt_agent.rb +17 -0
  134. data/lib/kward/shell/script_runner.rb +244 -0
  135. data/lib/kward/shell/standalone_agent.rb +31 -0
  136. data/lib/kward/shell/standalone_link.rb +78 -0
  137. data/lib/kward/shell/standalone_terminal.rb +287 -0
  138. data/lib/kward/terminal/keys.rb +22 -1
  139. data/lib/kward/terminal/locale_text.rb +29 -0
  140. data/lib/kward/terminal/sequences.rb +45 -4
  141. data/lib/kward/tools/datetime.rb +85 -0
  142. data/lib/kward/tools/generate_image.rb +36 -0
  143. data/lib/kward/tools/registry.rb +35 -9
  144. data/lib/kward/tools/tool_call.rb +3 -1
  145. data/lib/kward/transcripts/markdown_transcript.rb +8 -0
  146. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  147. data/lib/kward/transport/gateway.rb +2 -1
  148. data/lib/kward/turn_summary.rb +68 -0
  149. data/lib/kward/version.rb +1 -1
  150. data/lib/main.rb +6 -3
  151. metadata +84 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6ab55d26a014211a33f370b7bdf8d42de5d46723471ac26abc7ab893e2c41391
4
- data.tar.gz: 0a48ff5db83fe90318d252b817e6addcff3108bd51f8afd843785cc64aa13b02
3
+ metadata.gz: d5f437e5a636602d7742b14f118fd9232cc518c4b796089ae069b6a26edbb276
4
+ data.tar.gz: 135a464bab9b9c844940739243545d5c05a786a4b9757debc001e621b25e6bb7
5
5
  SHA512:
6
- metadata.gz: bf2be9c210d40d005736f385ea74c34158339e850b7bd1a2945174a85798fccd898cbd8ddeebc707559bc70028551706cc6dbafef6abf96632b74d4e7162aa65
7
- data.tar.gz: aa45a82d92d3c42af471d633e5d83ee80d5131e51c855be07e050b8fef1e468e1d6be459e2ba1741ab762df2a4a7dac6bbce1e4e4cf43ed32bda8f4611c10aa8
6
+ metadata.gz: 59254bfcee2caf48063b513dd78f1135edaadb4bbb39eb1dc8d929943398e9f60cf60df600d4d588ec854885607d60a1ad1322f689b9e7e3fd06e5108971d733
7
+ data.tar.gz: 993c21c4ba06234d834c72e64c81093d70c5bbbfcb0db04cb4d9c98471b4d9c4a210a6d61733ab6bb76cfc138cc5c54172fe5e934c034baa1da2dc4d4e85f545
data/CHANGELOG.md CHANGED
@@ -4,6 +4,136 @@ All notable changes to Kward will be documented in this file.
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.86.0] - 2026-11-22
8
+
9
+ ### Changed
10
+
11
+ - Enable automatic color for commands such as macOS `ls` in interactive `kward shell`, without overriding `TERM=dumb` or changing script environments.
12
+
13
+ - Execute interactive `kward shell` startup files as native shell scripts. The native `source` builtin works like `.`, while hosted `/shell` configuration and its top-level `source` command remain declarative.
14
+
15
+ - Require `kward prompt <text>` for one-shot model prompts and add `kward filter <instruction>` for explicit stdin filtering; unknown CLI arguments now fail instead of being sent to the model.
16
+ - Initialize the model client before launching interactive chat so the configured model catalog and picker are available at startup.
17
+
18
+ - Merge opt-in shell history across terminals and browse matching commands with Up/Down after typing a prefix.
19
+
20
+ - Cycle through ambiguous standalone shell completions with Tab and Shift+Tab, and accept a match without running the command.
21
+
22
+ - Display and edit pasted multiline drafts on separate terminal rows before submitting them.
23
+
24
+ - Show the command and stream its output live when the standalone `kward shell` agent runs it for you.
25
+
26
+ ### Added
27
+
28
+ - Press `Ctrl+N` in the chat composer to start a new conversation in the current tab, just like `/new`.
29
+
30
+ - Press `Ctrl+Shift+T` to open a new tab immediately to the right of the current tab when using the Ctrl tab shortcuts in a terminal that reports the chord.
31
+
32
+ - Support rbenv’s Bash initialization in interactive `kward shell`, with function-local variables and indexed arrays, `rbenv shell`, and programmable Tab completion.
33
+
34
+ - Pause standalone shell history and shell-agent context capture with `history pause`, then restore recording with `history resume`.
35
+
36
+ - Show local history suggestions in standalone shell drafts; press Right Arrow to accept a suggestion.
37
+
38
+ - Added `kward shell` to run native kwsh directly in your terminal without starting the agent or composer at launch. Use `?` to ask the same shell agent as `/shell` about recent output, run an explicit command, or prefill an editable command draft. Interactive sessions execute `kwshrc` startup scripts. The standalone prompt has Tab completion, arrow-key history and editing, bracketed paste, and native job control.
39
+
40
+ - Customize interactive `kward shell` with Zsh-style `PROMPT` escapes for colors, the current directory, username, host, and exit status. Unset `PROMPT` to return to `PS1`.
41
+
42
+ - Move and cut by word in `kward shell` with Option/Alt shortcuts and Ctrl+W. Ctrl+K cuts to the end of the line, and Ctrl+Y restores text cut by these shortcuts or Ctrl+U.
43
+
44
+ - Search standalone shell history with Ctrl+R/Ctrl+S. The default editor also supports screen redraw, transpose, undo, inserting the previous command’s last word, and cycling through older cuts.
45
+
46
+ - Generate images by asking in a Codex chat. Kward previews the result and can save it to Downloads or a project directory chosen with Tab completion. RPC clients can fetch, save, and discard previews.
47
+
48
+ - Added Claude Fable 5.2, Mythos 5.2, Opus 5.5, Sonnet 5.5, and Haiku 5.5 to the Anthropic model picker.
49
+ - Added GPT-6.2 Astra, GPT-6.2 Sol, and GPT-6.1 Terra to the Codex model picker, with model-specific reasoning controls and context-window metadata.
50
+ - Added native POSIX.1-2024 `ulimit` queries and settings for file/core size, data, descriptors, stack, CPU time, and address space, with soft/hard selection and owned-process isolation from the Kward host and other sessions.
51
+
52
+ - Added standalone native vi line editing with history search, motions/operators, repeat/undo, pathname expansion, and private external-vi editing. Terminal modes and command stdin are preserved; RPC reports history, line editing, and mail notifications as unsupported.
53
+
54
+ - Added native PS4 parameter expansion, standalone PS1 history numbering, terminal `ignoreeof`, compatible no-op `nolog`, and MAIL/MAILPATH/MAILCHECK notifications.
55
+
56
+ - Added standalone native command history and `fc` listing, substitution, and private editor workflows, with opt-in `HISTFILE` persistence and `HISTSIZE` retention. Hosted history remains separate.
57
+
58
+ - Standalone kwsh now supports inherited descriptors 3–9 for redirection, duplication, closing, native scripts, child commands, and executable-text fallback, without exposing hosted private descriptors.
59
+
60
+ - Added bounded multi-character locale collation across native case patterns, parameter trimming, and globs, plus requirement-linked POSIX and installed-locale regression coverage.
61
+ - Added native shared-stream aliases, core builtin flag combinations, command hashing, `type`, `times`, `CDPATH`, and standalone interactive `kwsh -i` with guarded `ENV` startup and parameter-expanded prompts.
62
+ - Added POSIX arithmetic-expansion substitutions, `case ;&` fall-through, and source-aware `LINENO`; new shells reset inherited `IFS`, and `command -V` follows function/builtin execution precedence.
63
+ - Added native kwsh background lists, `$!`, jobs/wait/kill, stopped-job foreground/background control, signal/EXIT traps, persistent exec redirections, and standalone process replacement, with tab-owned cleanup for hosted shells.
64
+ - Added read-time native aliases, incremental script execution, named-user and assignment-context tildes, and installed-locale character counts, bracket matching, pathname expansion, and sorting.
65
+
66
+ - Expanded native kwsh with subshells, nested command/process substitution, here-documents, descriptors 0–9, bounded extended arithmetic and arithmetic loops, indexed/associative arrays, `[[ … ]]`, brace expansion, opt-in globstar, native dot-sourcing and state utilities, read delimiters, shell options, and a standalone `kwsh` executable. Full POSIX/Bash conformance remains unfinished; documented limits remain explicit.
67
+ - Added native kwsh parameter operators, `case` pattern matching, `read -r`, and custom/empty `IFS`, with lazy nested expansion, quote-preserving splitting, and line-reading workflows. This is the first stage toward broader POSIX scripting and Bash-compatible extensions, not full compatibility.
68
+ - Added native kwsh integer arithmetic expansion (`$((5 + 2))`), with basic operators, grouping, integer-valued variables, bounded evaluation, and shell-assistant guidance for the supported syntax. A kwsh-specific extension also accepts spaces or tabs between the final closing parentheses (`$((5 + 2) )`).
69
+ - Added native kwsh scripting inside `/shell`: multiline programs, quoted variables and arguments, conditionals, loops, functions, pipelines, ordered redirection, and isolated `kwsh <file> [args]` execution, without delegating the language to another shell.
70
+ - Added RPC model-picker eligibility and safe provider refresh outcomes, with consistent catalog refresh/fallback behavior and explicit cross-process reload guidance.
71
+ - Added cached-input counts and cache-hit rate, cache-write counts, and reasoning-token counts to detailed turn statistics, preserving unavailable versus reported-zero fields and marking partial breakdowns.
72
+ - Added persistent turn-end elapsed time, token usage, and tool-call summaries across CLI/TUI, RPC, Pan, and transcript exports, with compact/detailed/off display modes and explicit partial or unavailable usage.
73
+ - Added `--ignore-local-instructions` to suppress workspace `AGENTS.md` guidance and project skills for a CLI run while retaining user-level instructions and skills.
74
+ - Added an example `--openrouter-proxy` plugin that serves authenticated, loopback-only OpenRouter Chat Completions requests through Kward's Codex account, with non-streaming and SSE translations and strict JSON-schema output support.
75
+ - Added a local deterministic fake embeddings endpoint to the example OpenRouter proxy, with configured model IDs, bounded dimensions and batches, and no upstream embedding requests.
76
+ - Added a plugin-host Codex Responses streaming client using Kward's OAuth credentials and the documented ChatGPT-plan API endpoint, with storage disabled and safe provider errors.
77
+ - Added a managed, loopback-only HTTP listener to identified plugin hosts with bounded requests and automatic cleanup on reload or shutdown.
78
+ - Added declarative, identified-plugin CLI startup options for foreground modes, parsed before normal command dispatch and activated only when selected.
79
+ - Added the model-callable `datetime` tool for current local/offset time and ISO 8601 timestamp arithmetic with fixed UTC offsets.
80
+
81
+ ### Changed
82
+
83
+ - Native kwsh now interprets executable text after an `ENOEXEC` error, including shebangless scripts found through `PATH` and invoked with `exec`, without delegating to another shell. Permission failures and binary-looking files remain rejected; standalone PID replacement and hosted job ownership are preserved.
84
+ - Native `. file` now executes script code consistently in `/shell`; `source file` remains declarative configuration loading. Native aliases apply to subsequent complete input units instead of being reparsed at execution time. Locale selection follows LC_ALL/category/LANG precedence, defaulting to C; unavailable locales error explicitly. Hosted exec closes the logical session without replacing its control-channel worker, and USR2 is reserved for shutdown.
85
+ - Restored the interactive composer's original Braille spinner and animation pace while retaining activity labels, elapsed time, and completion indicators.
86
+ - Removed decorative prefixes from assistant and user transcript labels, retaining speaker names and colors.
87
+ - Replaced the persistent `/shell` system-shell evaluator with kwsh's deliberately limited POSIX-style interpreter. Unsupported syntax now errors explicitly rather than inheriting the host shell's language; declarative rc loading and the separate one-off/model/RPC command paths retain their existing behavior.
88
+ - Routed plugin-host Codex streaming and the OpenRouter proxy through Kward's normal Codex provider client and configured subscription credentials, rather than the public Responses API path.
89
+
90
+ ### Fixed
91
+
92
+ - Keep Ctrl+Z working for foreground jobs when the launcher ignores job-control stop signals.
93
+ - Keep standalone shell history in memory if saving it would exceed the file-size limit, rather than terminating the shell.
94
+ - Restore the previous terminal screen after `kward edit` and after leaving full-screen Git logs in `kward shell` with the default pager settings.
95
+ - Use every terminal row in the editor, both inside chat and when launched with `kward edit`.
96
+ - Show the active alias in kwsh’s `which` output instead of reporting the shadowed executable.
97
+ - Return to the shell prompt below the Kward transcript on exit, rather than jumping to the top of the screen.
98
+ - Keep interactive plugin games open when pressing Command or Shift. Only plain Esc exits by default; plugins can define additional quit keys.
99
+ - Keep inline Kitty graphics and capability-probe output visible when the shell prompt returns.
100
+ - Forward lone Escape and legacy Alt keys to shell PTYs without collapsing combined modifiers into control signals.
101
+ - Keep detached shell output on the same line across PTY reads.
102
+ - Restore the current terminal size on new shell PTYs, including after a `/shell` worker restarts.
103
+ - Preserve wide characters, combining accents, and backspace redraws in shell transcript replay.
104
+ - Bound the size of shell transcript replay when a command uses cursor movement.
105
+ - Keep busy composer headers on one line in narrow panes, dropping the cancel hint before clipping the activity text.
106
+ - Keep the draft and cursor visible in short panes by collapsing tabs, footers, and overlays as space runs out, while leaving room for transcript scrolling.
107
+ - Keep the composer cursor steady during spinner and status redraws, and refresh the header and footer even when the spinner is paused or the composer is idle.
108
+ - Prevent standalone modifier presses, such as Cmd or Shift, from printing escape sequences while an interactive shell command runs.
109
+ - Keep pending terminal image previews available when a queued follow-up starts before the preview opens.
110
+ - Return an empty final chunk when an RPC image fetch starts exactly at the end of the image.
111
+ - Native dot-sourcing now continues searching `PATH` when a matching file cannot be opened, selecting the first readable candidate as required.
112
+ - Native `getopts` error diagnostics now identify the invoking shell, including for unknown options and missing option arguments.
113
+ - Standalone `read` now displays the parameter-expanded `PS2` prompt on interactive backslash-newline continuations.
114
+ - Native `type` now rejects a missing operand, and `kill -s name` / `kill -name` accept case-independent signal names as required by POSIX.
115
+
116
+ - Removed native arithmetic's 4,096-byte expression ceiling and recursive evaluation of flat binary chains. Long non-overflowing expressions and zero-padded integers now work; precision, nesting, and other safety policies remain explicit in the resource-limit inventory.
117
+
118
+ - Failed standalone interactive kwsh `exec` now recovers for a fresh submission while retaining successful redirections. Internal IO, directory, mask, and signal state is restored; descriptor reservation keeps Ruby VM handles out of the shell's 3–9 range.
119
+
120
+ - Corrected native kwsh interactive signal defaults, protected inherited ignored signals, and made `trap -p` output include defaults and survive subshell save/restore. Interrupted `wait` traps now observe the wait status and run before `errexit`; hosted shutdown ownership is unchanged.
121
+
122
+ - Kept native shell directory identity across renames for execution, sourcing, redirection and globbing, with owned close-on-exec handles and no host cwd changes. Logical `cd` now validates components before removing `..`.
123
+ - Completed native `umask` symbolic permission copying, sequential operations and `-S`/`--` handling, and added `cd -P -e` pathname-reporting status without undoing successful directory changes.
124
+ - Corrected native alias names and quoted listing output, and traced expanded assignment-only commands without evaluating substitutions twice.
125
+ - Corrected native kwsh startup `PPID`/`OPTIND`, standalone inherited logical `PWD` validation, invocation-derived `$0`, and leading `-` operand handling, while preserving hosted workspace ownership and stdin command boundaries.
126
+ - Fixed native shell redirection operands being split/globbed, here-document continuation order, and premature execution of backslash-continued input lines.
127
+ - Protected TUI tab shortcuts across shell keyboard-mode changes and screen switches, restored composer terminal modes on handback, and hardened fragmented key and bracketed-paste handling without unbounded output buffering.
128
+ - Corrected native kwsh fatal-error handling and POSIX `errexit` inheritance, preserving interactive recovery, subshell isolation, special-builtin behavior through `command`, and EXIT traps.
129
+ - Kept `/shell` background servers responsive after `bg` by draining idle PTY output instead of letting logs fill the terminal buffer and block further requests; idle output is discarded, so redirect jobs to files to retain logs.
130
+ - Fixed native kwsh jobs intermittently stopping again after Ctrl-Z followed by `bg`, by checking for newer continuation or exit events before propagating a child stop report.
131
+ - Kept terminal transcript image attachments badge-only to prevent misplaced graphics during scrolling and redraws, while preserving `/files` image previews and model image input.
132
+ - Displayed Codex commentary as assistant speech instead of reasoning in live CLI/TUI, RPC, and Pan output and restored CLI/RPC transcripts, without folding it into the final answer.
133
+ - Avoided double-counting cached input when deriving token totals, and normalized separately reported Anthropic cache tokens into inclusive input counts for cache-hit rates.
134
+ - Fixed OpenRouter proxy Chat Completions failing while adapting Kward's symbol-keyed model messages.
135
+ - Kept the active tab visible in the composer tab bar when tabs overflow, with indicators for hidden tabs.
136
+
7
137
  ## [0.85.0] - 2026-10-05
8
138
 
9
139
  ### Added
data/CONTRIBUTING.md CHANGED
@@ -23,7 +23,7 @@ Run the CLI from the checkout with:
23
23
 
24
24
  ```bash
25
25
  ruby lib/main.rb
26
- ruby lib/main.rb "Explain this project"
26
+ ruby lib/main.rb prompt "Explain this project"
27
27
  ```
28
28
 
29
29
  See [Platform support](doc/platform-support.md) for operating-system and terminal expectations.
data/Gemfile.lock CHANGED
@@ -1,8 +1,9 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- kward (0.85.0)
4
+ kward (0.86.0)
5
5
  base64
6
+ fiddle
6
7
  nokogiri
7
8
  tiktoken_ruby
8
9
  tty-cursor
@@ -10,6 +11,7 @@ PATH
10
11
  tty-reader
11
12
  tty-screen
12
13
  unicode-display_width
14
+ webrick
13
15
 
14
16
  GEM
15
17
  remote: https://rubygems.org/
@@ -43,6 +45,7 @@ GEM
43
45
  fiber-local (1.1.0)
44
46
  fiber-storage
45
47
  fiber-storage (1.0.1)
48
+ fiddle (1.1.8)
46
49
  hashery (2.1.2)
47
50
  html-proofer (5.2.1)
48
51
  addressable (~> 2.3)
@@ -146,11 +149,12 @@ CHECKSUMS
146
149
  fiber-annotation (0.2.0) sha256=7abfadf1d119f508867d4103bf231c0354d019cc39a5738945dec2edadaf6c03
147
150
  fiber-local (1.1.0) sha256=c885f94f210fb9b05737de65d511136ea602e00c5105953748aa0f8793489f06
148
151
  fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
152
+ fiddle (1.1.8) sha256=7fa8ee3627271497f3add5503acdbc3f40b32f610fc1cf49634f083ef3f32eee
149
153
  hashery (2.1.2) sha256=d239cc2310401903f6b79d458c2bbef5bf74c46f3f974ae9c1061fb74a404862
150
154
  html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
151
155
  io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
152
156
  json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
153
- kward (0.85.0)
157
+ kward (0.86.0)
154
158
  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
155
159
  metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
156
160
  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
data/README.md CHANGED
@@ -51,8 +51,8 @@ kward login # sign in or save provider credentials
51
51
  kward # start an interactive chat
52
52
  kward help # show available commands and examples
53
53
  kward hooks doctor # inspect lifecycle hook setup
54
- kward "Explain this project" # run one prompt and exit
55
- kward --working-directory ~/code/project "Explain this project"
54
+ kward prompt "Explain this project" # run one prompt and exit
55
+ kward --working-directory ~/code/project prompt "Explain this project"
56
56
  ```
57
57
 
58
58
  From inside Kward, `/login` lets you choose API-key or subscription authentication across supported providers. `/model` then switches providers, refreshes model catalogs, or accepts a manual model/deployment ID. Direct OpenAI API credentials and ChatGPT/Codex OAuth can coexist.
@@ -95,7 +95,7 @@ Everyday workflows:
95
95
  - [Project files](doc/files.md): browse, search, mention, open, and edit workspace files.
96
96
  - [Integrated editor](doc/editor.md): open files from the shell or composer, edit in-place, and choose editor keybindings.
97
97
  - [Git](doc/git.md): review changes, use the diff viewer, stage files, and commit from the interactive TUI.
98
- - [Shell](doc/shell.md): use `/shell`, the embedded Kward shell with aliases, completion, and per-tab state.
98
+ - [Shell](doc/shell.md): run `kward shell` for a standalone shell without logging in, or use `/shell` for the embedded shell with per-tab state. In either shell, start a line with `?` to ask the agent about your last command.
99
99
  - [Memory](doc/memory.md): opt-in core, soft, and session memory.
100
100
  - [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
101
101
  - [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
data/Rakefile CHANGED
@@ -93,7 +93,10 @@ def verify_public_api_docs
93
93
  required_links = [
94
94
  "Kward.html#plugin-class_method",
95
95
  "Kward/PluginRegistry/DSL.html",
96
+ "Kward/PluginRegistry/DSL.html#startup_option-instance_method",
96
97
  "Kward/PluginRegistry/Context.html",
98
+ "Kward/PluginHTTPServer.html",
99
+ "Kward/PluginCodexResponses.html",
97
100
  "Kward/Tools/Base.html",
98
101
  "Kward/ToolRegistry.html",
99
102
  "Kward/RPC/Server.html",
data/doc/agent-tools.md CHANGED
@@ -18,10 +18,20 @@ Tools also enforce important boundaries:
18
18
  | Shell prompt tools | `run_shell_command`, `prepare_shell_command` (available only to the transient `?` shell assistant) | [Embedded shell](shell.md) |
19
19
  | Web tools | `web_search`, `fetch_content`, `fetch_raw` | [Web search](web-search.md) |
20
20
  | Code search | `code_search` | [Code search](code-search.md) |
21
+ | Date/time | `datetime` | Current time and timestamp arithmetic (details below) |
21
22
  | Context and interaction tools | `read_skill`, `retrieve_tool_output`, `ask_user_question` | [Context tools](context-tools.md) |
22
23
  | Decision tools | `typesafe_evaluate` when `TYPESAFE_API_KEY` is configured | [TypeSafe](#TypeSafe_evaluation) |
23
24
  | Plugin tools | Trusted local integrations registered by installed plugins | [Plugins](plugins.md#Add_a_model_callable_tool) |
24
25
 
26
+ ## Date and time
27
+
28
+ The `datetime` tool supports two operations:
29
+
30
+ - `current_time` returns the current date and time in the host's local timezone by default. Supply `timezone_offset` as `Z` or an ISO 8601 UTC offset such as `-05:00` to request a fixed offset.
31
+ - `add_seconds` accepts an ISO 8601 `timestamp` with an explicit offset and a signed integer `seconds` value, then returns the adjusted timestamp while preserving that offset.
32
+
33
+ UTC offsets are fixed offsets, not named timezones; they do not apply daylight-saving transitions.
34
+
25
35
  ## How tools save tokens
26
36
 
27
37
  Kward tries to gather enough evidence without flooding the conversation. It usually starts with focused context tools, then moves from outlines and previews to exact ranges or full files only when needed:
@@ -47,6 +57,7 @@ See [Context budgeting](context-budgeting.md) for the full compaction strategy,
47
57
  - `ask_user_question` is advertised only when the frontend can display structured questions,
48
58
  - `typesafe_evaluate` is advertised only in normal turns when `TYPESAFE_API_KEY` is configured,
49
59
  - plugin tools are advertised in normal agent turns and remain subject to execution profiles and permission policy.
60
+ - `datetime` is available in normal agent turns and remains subject to the configured tool permission policy.
50
61
 
51
62
  ### TypeSafe evaluation
52
63
 
data/doc/api.md CHANGED
@@ -15,7 +15,7 @@ If you use Kward from the terminal, start with the [user guides](file.README.htm
15
15
 
16
16
  ### Plugin authors
17
17
 
18
- Use plugins when you need trusted local Ruby code for typed commands and actions, model-callable tools, prompt context, footer UI, transcript events, plugin-owned chats, or external transports.
18
+ Use plugins when you need trusted local Ruby code for typed commands and actions, model-callable tools, prompt context, footer UI, transcript events, plugin-owned chats, external transports, or managed local HTTP and provider access.
19
19
 
20
20
  Session commands can stage a host-owned model response with
21
21
  `ctx.request_turn(system: text)`; check `ctx.turn_requests_supported?` before
@@ -36,7 +36,10 @@ Generated entry points:
36
36
  - [`Kward::PluginCommand`](Kward/PluginCommand.html)
37
37
  - [`Kward::PluginAction`](Kward/PluginAction.html)
38
38
  - [`Kward::PluginResult`](Kward/PluginResult.html)
39
+ - [`Kward::PluginRegistry::DSL#startup_option`](Kward/PluginRegistry/DSL.html#startup_option-instance_method)
39
40
  - [`Kward::PluginHost`](Kward/PluginHost.html)
41
+ - [`Kward::PluginHTTPServer`](Kward/PluginHTTPServer.html)
42
+ - [`Kward::PluginCodexResponses`](Kward/PluginCodexResponses.html)
40
43
  - [`Kward::PluginStore`](Kward/PluginStore.html)
41
44
  - [`Kward::PluginScopedStore`](Kward/PluginScopedStore.html)
42
45
  - [`Kward::PluginChatCapabilities`](Kward/PluginChatCapabilities.html)
data/doc/composer.md CHANGED
@@ -40,6 +40,7 @@ The composer supports familiar line-editing keys:
40
40
  | `Ctrl+Y` | Yank the most recently killed composer text |
41
41
  | `Ctrl+L` | Redraw the terminal UI and remove transient current-view output |
42
42
  | `Ctrl+D` | Delete at the cursor, or exit when the composer is empty |
43
+ | `Ctrl+N` | Start a new conversation in the current tab, just like `/new`; discards the current draft |
43
44
 
44
45
  These are composer bindings. The integrated editor, shell, Git view, file browser, and plugin interfaces have their own keymaps.
45
46
 
@@ -127,11 +128,11 @@ Tab follows the normal completion behavior:
127
128
 
128
129
  `Ctrl+Tab` and `Ctrl+Shift+Tab` switch conversations when your terminal reports those keys. Additional shortcuts depend on `composer.tab_keybindings`:
129
130
 
130
- - `ctrl`: `Ctrl+T` creates a tab, `Ctrl+W` closes one, and reported `Ctrl+1` through `Ctrl+9` select numbered tabs.
131
+ - `ctrl`: `Ctrl+T` creates a tab at the end, `Ctrl+Shift+T` creates one immediately to the right of the current tab if your terminal reports it, `Ctrl+W` closes one, and reported `Ctrl+1` through `Ctrl+9` select numbered tabs.
131
132
  - `alt`: `Alt+T` creates a tab, `Alt+Left`/`Alt+Right` move between tabs, and `Alt+1` through `Alt+9` select numbered tabs.
132
133
  - `auto`: prefers the Ctrl family on macOS and the Alt family elsewhere.
133
134
 
134
- Use `/settings` → Interface → Tab keybindings to change the family. If your terminal intercepts a shortcut, `/tab` commands always provide the same operations.
135
+ Use `/settings` → Interface → Tab keybindings to change the family. If your terminal intercepts a shortcut, you can use `/tab` commands instead. For example, to open a tab next to the current one, use `/tab new`, then `/tab move <number>` to put it where you want it.
135
136
 
136
137
  See [Tabs](tabs.md) for background work, status colors, persistence, naming, and moving tabs.
137
138
 
@@ -186,7 +187,7 @@ Example:
186
187
 
187
188
  If the cursor is at the start of an otherwise empty draft, Backspace removes the most recently added pending attachment. Submitting the draft clears its pending attachments.
188
189
 
189
- The active model must support image input. iTerm2 and Kitty-compatible terminals can render submitted images inline; Kward uses active Kitty capability detection when running on a real TTY and falls back to conservative terminal hints otherwise. Other terminals still show attachment badges and send the image to the model without an inline preview.
190
+ The active model must support image input. Submitted images appear as attachment badges in the terminal transcript, including restored sessions. Images are still sent to the model; inline graphics are omitted so transcript scrolling and redraws stay reliable. To view an image locally, open it through [`/files`](files.md#Image_previews), which retains image previews on supported iTerm2 and Kitty-compatible terminals.
190
191
 
191
192
  ## Understand composer status
192
193
 
data/doc/configuration.md CHANGED
@@ -188,11 +188,11 @@ Use `failure_policy` (`allow`, `warn`, `deny`, or `ask`) to decide what happens
188
188
 
189
189
  Project-local hooks can also live in `.kward/hooks.json`, but Kward loads them only after you explicitly run `/hooks trust` in that workspace. Trust is tied to the file digest, so changes require re-trusting. See [Lifecycle hooks](lifecycle-hooks.md) for events, decisions, selectors, plugin hooks, command-hook protocol, workspace trust, and security notes.
190
190
 
191
- ## Embedded shell config
191
+ ## Shell configuration
192
192
 
193
- The embedded Kward shell (`/shell`, internally `kwsh`) reads the shell-style rc files `~/.kward/kwshrc` and `~/.kwshrc`, in that order. When `KWARD_CONFIG_PATH` is set, the first path is beside that config file instead. Later rc entries override earlier aliases and exported variables.
193
+ Interactive `kward shell` and the hosted `/shell` both load `~/.kward/kwshrc` and then `~/.kwshrc`, but only the standalone shell **executes** them. When `KWARD_CONFIG_PATH` selects another main config file, Kward looks for the first `kwshrc` beside that file instead. The separate `kwsh` executable and non-interactive `kward shell` do not load these files automatically.
194
194
 
195
- Example rc file:
195
+ For settings shared with `/shell` and leading-`!` commands, stick to declarative directives:
196
196
 
197
197
  ```sh
198
198
  alias ll='ls -la'
@@ -202,11 +202,11 @@ export PATH="$HOME/bin:$PATH"
202
202
  source ~/.kward/kwsh-aliases
203
203
  ```
204
204
 
205
- Only declarative `alias`, `export`, and `source` (or `.`) directives are handled. `source` parses the referenced file without executing it, resolving relative paths from the containing rc file. Other shell scripting is ignored for now.
205
+ In standalone `kward shell`, you can also write functions, `if` statements, and other native shell code. `source` works like `.`: it executes the file in the current shell, looks up bare names on `PATH`, and resolves paths such as `./other.rc` from the working directory. Load only files you trust. The hosted loader does not execute shell code; it reads only `alias`, `export`, and `source` (or `.`), and it resolves relative includes from the containing rc file. See the [Shell guide](shell.md) for startup examples and how `ENV` fits in.
206
206
 
207
207
  ### Shell-agent model
208
208
 
209
- The transient shell assistant normally follows the active conversation's model and reasoning effort. Override those defaults in the main JSON configuration:
209
+ By default, the hosted `/shell` agent uses the active conversation's provider, model, and reasoning effort. The standalone `kward shell` agent starts from Kward's configured selection. Override either default in the main JSON configuration:
210
210
 
211
211
  ```json
212
212
  {
@@ -220,9 +220,9 @@ The transient shell assistant normally follows the active conversation's model a
220
220
  }
221
221
  ```
222
222
 
223
- The optional `provider` selects a different backend for the transient shell assistant. Use the lowercase configuration IDs listed in [Model providers](providers.md). When it is omitted, the shell assistant follows the active conversation's provider, model, and reasoning effort. If a provider is explicitly configured without a model or reasoning effort, Kward uses that provider's defaults rather than inheriting values from the active conversation.
223
+ The optional `provider` selects a different backend for the shell agent. Use the lowercase configuration IDs listed in [Model providers](providers.md). If you set an explicit provider but omit the model or reasoning effort, Kward uses that provider's defaults for the omitted settings.
224
224
 
225
- Environment variables take precedence over the JSON settings:
225
+ Environment variables exported before launching Kward take precedence over the JSON settings:
226
226
 
227
227
  ```sh
228
228
  export KWSH_PROVIDER="openrouter"
@@ -232,9 +232,9 @@ export KWSH_REASONING="none"
232
232
 
233
233
  `KWSH_PROVIDER` selects the shell-agent provider, `KWSH_MODE` selects its model, and `KWSH_REASONING` selects its reasoning effort. Empty values are ignored.
234
234
 
235
- `export` values are applied when shell mode starts, after Kward's conservative color defaults, and are also available to leading-`!` commands. Keys must be valid environment-variable names; invalid keys are ignored. Values support shell quoting and simple `$VAR`/`${VAR}` expansion. `/shell` keeps one persistent local interactive shell process per tab.
235
+ The declarative exports read by `/shell` and leading-`!` commands support shell quoting and simple `$VAR`/`${VAR}` expansion. Invalid variable names are ignored. The hosted shell applies these exports after Kward’s conservative color defaults and keeps one persistent local shell process per tab.
236
236
 
237
- `alias` entries expand the first word of a command once. For example, `alias ll='ls -la'` makes `ll lib` run `ls -la lib`. Configured aliases are available both inside `/shell` and after the normal composer's `!` prefix, including command-name Tab completion. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `kwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current `/shell` session and are not available to `!command` input.
237
+ `alias ll='ls -la'` makes `ll lib` run `ls -la lib`. Configured aliases are available in `kward shell`, `/shell`, and after the normal composer’s `!` prefix, including command-name Tab completion. Native aliases expand at parse time; the one-off `!` path replaces only the initial command name. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `kwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current shell session and are not available to `!command` input.
238
238
 
239
239
  ## Provider and model settings
240
240
 
@@ -284,7 +284,7 @@ Model settings:
284
284
 
285
285
  `model` is a legacy generic fallback. Provider-specific values take precedence. Catalog providers use `<runtime-id>_model`; for example, direct OpenAI uses `openai_api_model`, Gemini uses `gemini_model`, and Groq uses `groq_model`. Codex keeps `openai_model`. `reasoning_effort` and `thinking_level` are generic reasoning settings. `thinking_level` is an alias for `reasoning_effort` honored by all providers. For each provider, Kward resolves reasoning in this order: the provider-specific key (for example `openai_reasoning_effort`), then the generic `reasoning_effort`, then `thinking_level`, then the default `medium`. `openai_reasoning_effort`, `anthropic_reasoning_effort`, `openrouter_reasoning_effort`, and `copilot_reasoning_effort` are provider-specific forms.
286
286
 
287
- OpenAI-hosted models do not expose their raw reasoning tokens. Kward displays the reasoning summaries and visible Codex commentary they provide. Set `codex_show_raw_reasoning` to `true` only for a backend that emits raw Codex `reasoning_text`; it defaults to `false` because raw reasoning can include internal or unstable model output.
287
+ OpenAI-hosted models do not expose their raw reasoning tokens. Kward displays their reasoning summaries as reasoning, and visible Codex commentary (progress updates addressed to you) as assistant speech, including when restoring a session. Set `codex_show_raw_reasoning` to `true` only for a backend that emits raw Codex `reasoning_text`; it defaults to `false` because raw reasoning can include internal or unstable model output.
288
288
 
289
289
  `stream_idle_timeout_seconds` limits how long a streamed Codex, Anthropic, or Local response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
290
290
 
@@ -296,7 +296,7 @@ Defaults:
296
296
  - Copilot: `gpt-5-mini`
297
297
  - Reasoning effort: `medium`
298
298
 
299
- The OpenAI/Codex and Copilot model choices include `gpt-6-astra`. GPT-6 Astra has a 1,050,000-token context window and supports `low`, `medium`, `high`, `xhigh`, and `max` reasoning effort; it does not support `none`.
299
+ The Codex model choices include `gpt-6.2-astra`, `gpt-6.2-sol`, and `gpt-6.1-terra`. These models have a 1,050,000-token context window. GPT-6.2 Astra and Sol support `low`, `medium`, `high`, `xhigh`, and `max` reasoning effort; they do not support `none`. GPT-6.1 Terra also supports `none`. Model availability depends on account access.
300
300
 
301
301
  The Anthropic model choices include `claude-fable-5`, `claude-opus-5`, and `claude-sonnet-5`. Fable and Opus availability depends on the logged-in account and organization. Selecting a model without access returns an Anthropic provider error. Kward keeps Sonnet 5 as its default because it supports both Pro and Max subscriptions; select Opus 5 explicitly when it is available on the account.
302
302
 
@@ -429,6 +429,55 @@ In the normal composer prompt, choose reasoning effort with `/reasoning` or `/mo
429
429
 
430
430
  `auto` (default) detects terminal support, `ctrl` uses `Ctrl+Tab`/`Shift+Tab` to cycle suggestions and indent, `alt` uses `Alt+Tab` for terminals where `Ctrl+Tab` is swallowed.
431
431
 
432
+ ## Transcript turn statistics
433
+
434
+ By default, each agent turn ends with a compact summary:
435
+
436
+ ```text
437
+ Completed · 18.4s · 24.8k tokens · 4 tool calls
438
+ ```
439
+
440
+ Set `transcript.turn_stats` in `config.json` to `compact` (default), `detailed`,
441
+ or `off`:
442
+
443
+ ```json
444
+ {
445
+ "transcript": {
446
+ "turn_stats": "detailed"
447
+ }
448
+ }
449
+ ```
450
+
451
+ Detailed mode adds the number of model requests and an input/output token
452
+ breakdown, plus cached input, reasoning tokens, and cache writes when reported:
453
+
454
+ ```text
455
+ Completed · 18.4s · 24.8k tokens · 3 model requests · 4 tool calls
456
+ Input 23.6k · Cached 20.0k (85%) · Output 1.2k · Reasoning 800
457
+ ```
458
+
459
+ The cache-hit percentage uses total cached input divided by total input across
460
+ the turn, not an average of individual request percentages. Missing details are
461
+ omitted; explicitly reported zeroes are shown. If only some requests report a
462
+ field, its subtotal is marked `(partial)`. A cache-hit percentage is shown only
463
+ when both input and cache counts cover the complete turn and input is nonzero.
464
+ Cached tokens and cache writes are input breakdowns; reasoning tokens are part
465
+ of output. They are not added to total usage again. Availability depends on the
466
+ provider, endpoint, and model; the Codex subscription endpoint may report fewer
467
+ fields than the public OpenAI API.
468
+
469
+ Narrow terminals drop secondary fields rather than wrapping the summary. Invalid or missing values use `compact`. There is no dedicated
470
+ environment override; `KWARD_CONFIG_PATH` selects the configuration file as usual.
471
+
472
+ This preference controls CLI/TUI, Pan, and Markdown/HTML export presentation.
473
+ Stats are still saved and available as structured RPC data when display is off;
474
+ RPC clients own their rendering. Pan reads the preference when its server starts.
475
+ Filter mode keeps stdout answer-only. Editor/shell prompts and plugin-owned chats
476
+ do not automatically display these summaries.
477
+
478
+ See [turn statistics](session-management.md#Turn_statistics) for what the counts
479
+ include and how incomplete provider usage is shown.
480
+
432
481
  ## Editor settings
433
482
 
434
483
  The built-in TUI file editor supports three keybinding modes. Modern is the default:
data/doc/extensibility.md CHANGED
@@ -68,6 +68,8 @@ Use `AGENTS.md` for project facts and engineering rules. Do not put personality
68
68
 
69
69
  By default, Kward adds a compact instruction telling the model that `AGENTS.md` exists and should be read when relevant. Set `enforce_workspace_agents_file: true` only if you want the full file injected every time. See [Configuration](configuration.md) for details.
70
70
 
71
+ The transient `?` assistant inside `/shell` has its own scoped instructions and uses the [native kwsh scripting subset](shell.md). It knows which syntax is unsupported and must not silently invoke Bash or another shell to work around those limits. This does not change the normal agent's shell tools or skill activation.
72
+
71
73
  ## Prompt templates
72
74
 
73
75
  Use prompt templates when you repeatedly type the same kind of request. Each Markdown file in `~/.kward/prompts/` becomes a slash command; its filename is the command name and `$ARGUMENTS` expands the text after the command.
@@ -101,16 +101,16 @@ The composer footer highlights the two main discovery shortcuts: type `/` to bro
101
101
 
102
102
  ## Ask one question and exit
103
103
 
104
- For quick tasks, pass the prompt directly:
104
+ For quick tasks, use the explicit `prompt` command. This keeps a misspelled command from being sent to the model by accident:
105
105
 
106
106
  ```bash
107
- kward "Explain this project"
107
+ kward prompt "Explain this project"
108
108
  ```
109
109
 
110
110
  Review a diff:
111
111
 
112
112
  ```bash
113
- git diff | kward "Review this diff for bugs"
113
+ git diff | kward prompt "Review this diff for bugs"
114
114
  ```
115
115
 
116
116
  One-shot prompts do not use Kward memory.
data/doc/git.md CHANGED
@@ -127,5 +127,5 @@ Selecting `origin` does not add a separate approval prompt; the normal configure
127
127
  For AI-assisted review without committing, you can still pipe a diff into a one-shot prompt:
128
128
 
129
129
  ```bash
130
- git diff | kward "Review this diff"
130
+ git diff | kward prompt "Review this diff"
131
131
  ```
data/doc/memory.md CHANGED
@@ -11,7 +11,7 @@ Use memory when you keep telling Kward the same things:
11
11
 
12
12
  Leave memory off when every session should start clean.
13
13
 
14
- Memory is not used for one-shot prompts such as `kward "..."`.
14
+ Memory is not used for one-shot prompts such as `kward prompt "..."`.
15
15
 
16
16
  ## Enable memory
17
17
 
data/doc/plugins.md CHANGED
@@ -22,7 +22,7 @@ Plugins run inside the Kward process with your user permissions. Install only pl
22
22
  | Repository rules | `AGENTS.md` |
23
23
  | Local Ruby code or integration | plugin |
24
24
 
25
- See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations.
25
+ See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations. The [OpenRouter proxy example guide](https://github.com/kaiwood/kward/blob/main/examples/plugins/openrouter_proxy/README.md) documents its startup option, managed HTTP listener, and local fake embeddings.
26
26
 
27
27
  ## Where plugins live
28
28
 
@@ -162,6 +162,21 @@ an optional parent token with `cancellation:`.
162
162
  for automatic cleanup. `host.manage` is an alias. Cleanup runs in reverse
163
163
  registration order so dependent resources unwind predictably.
164
164
 
165
+ `host.http_server` creates a loopback-only managed HTTP listener. It defaults to
166
+ an ephemeral port, a 1 MiB maximum request size, a 30-second request timeout,
167
+ and eight clients. Pass an explicit port when a local application needs a stable
168
+ address. Start the server with `server.start`, inspect `server.port`, wait with
169
+ `server.wait`, and stop it with `server.stop`; plugin cleanup stops it
170
+ automatically. The handler receives WEBrick's request and response objects.
171
+
172
+ `host.codex_responses.stream(model:, input:, instructions: nil, text: nil)`
173
+ streams Responses-shaped events through Kward's normal Codex provider client,
174
+ using the configured Codex credentials and account context. It never returns the
175
+ authentication token. The caller should handle failed or incomplete turns. This
176
+ uses Kward's existing private Codex backend route and is coupled to that
177
+ undocumented endpoint; prefer it only when matching normal Kward Codex behavior
178
+ is required. Do not read Kward's auth files directly.
179
+
165
180
  Plugin-owned tab hosts expose the same `background`, `on_cleanup`, and `manage`
166
181
  methods. Their resources are cleaned up when a local tab closes or its shared
167
182
  plugin-chat runtime shuts down. A tab driver may implement `close` (or `shutdown`
@@ -172,6 +187,25 @@ Do not open network connections or start threads directly while the plugin file
172
187
  is loading. Register them from `on_start`, a command, or a plugin-tab factory so
173
188
  Kward can own their lifetime.
174
189
 
190
+ ## Add a top-level startup option
191
+
192
+ Identified plugins can declare a no-argument switch for a foreground CLI mode:
193
+
194
+ ```ruby
195
+ Kward.plugin(id: "com.example.server", version: "1.0.0", api: 1) do |plugin|
196
+ plugin.startup_option("--example-server", description: "Run the example server") do |host|
197
+ ExampleServer.new(host).run
198
+ end
199
+ end
200
+ ```
201
+
202
+ The handler is called only when the user selects the option. Kward loads plugin
203
+ registrations to identify plugin-owned switches before normal command dispatch,
204
+ but does not start lifecycle callbacks or run the handler unless the mode is
205
+ selected. A startup option cannot be combined with a prompt or another startup
206
+ option. Keep loading code side-effect-free; the handler should own the selected
207
+ foreground mode and return when it stops.
208
+
175
209
  ## Add a slash command
176
210
 
177
211
  Use plugin commands for local actions that should not call the model.
@@ -534,7 +568,7 @@ Kward.plugin do |plugin|
534
568
  ui.put(0, x, "X", :red)
535
569
  x = (x + 1) % ui.width
536
570
  key = ui.poll_key
537
- return :exit if key == :ctrl_c || key == "q"
571
+ next :exit if key == "q"
538
572
  ui.render
539
573
  end
540
574
  end
@@ -562,8 +596,9 @@ The `ui` controller object passed to the handler block exposes:
562
596
  | `fps` | Target frame rate |
563
597
 
564
598
  Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
565
- `:backspace`, `:space`, `:pageup`, `:pagedown`) or raw strings for keys
566
- without a named mapping. Ctrl+C always exits the loop immediately.
599
+ `:backspace`, `:space`, `:pageup`, `:pagedown`, `:ctrl_c`) or raw strings for keys
600
+ without a named mapping. Kward exits on plain Esc. To add a quit key such as `q`
601
+ or Ctrl+C, handle it in the tick callback and call `ui.exit` or return `:exit`.
567
602
 
568
603
  The tick callback runs at the configured frame rate (1–120 fps, default 30).
569
604
  Calls to `put` and `clear_frame` stage canvas changes; call `render` after the
@@ -577,7 +612,7 @@ Returning `:exit` from the tick callback ends the loop, same as calling
577
612
  cursor, and transcript viewport).
578
613
  - Interactive mode is a distinct state from the busy-input spinner lifecycle —
579
614
  no spinner or busy chrome is shown.
580
- - Ctrl+C, the plugin calling `exit`, or the tick callback returning `:exit`
615
+ - Plain Esc, the plugin calling `exit`, or the tick callback returning `:exit`
581
616
  all exit cleanly and restore the prior composer state.
582
617
  - Resize during interactive mode forces a clean exit and restore.
583
618