kward 0.84.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 (245) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +164 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +5 -5
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +24 -1
  8. data/doc/api.md +20 -2
  9. data/doc/composer.md +5 -4
  10. data/doc/configuration.md +86 -14
  11. data/doc/extensibility.md +4 -1
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +4 -2
  14. data/doc/memory.md +1 -1
  15. data/doc/pan.md +6 -0
  16. data/doc/permissions.md +4 -4
  17. data/doc/plugins.md +504 -20
  18. data/doc/providers.md +10 -4
  19. data/doc/rpc.md +279 -23
  20. data/doc/sandboxing.md +11 -5
  21. data/doc/security.md +7 -1
  22. data/doc/session-management.md +41 -5
  23. data/doc/shell.md +643 -27
  24. data/doc/tabs.md +8 -3
  25. data/doc/transports.md +15 -0
  26. data/doc/troubleshooting.md +1 -1
  27. data/doc/usage.md +25 -12
  28. data/doc/workspace-tools.md +9 -0
  29. data/examples/plugins/openrouter_proxy/README.md +103 -0
  30. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  31. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  32. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  33. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  34. data/examples/plugins/space_invaders.rb +1 -2
  35. data/examples/plugins/stardate_footer.rb +2 -2
  36. data/examples/plugins/telegram/plugin.rb +1 -1
  37. data/exe/kward +2 -2
  38. data/exe/kwsh +7 -0
  39. data/kward.gemspec +3 -1
  40. data/lib/kward/agent.rb +66 -19
  41. data/lib/kward/cli/commands.rb +41 -11
  42. data/lib/kward/cli/compaction.rb +9 -3
  43. data/lib/kward/cli/interactive_turn.rb +10 -0
  44. data/lib/kward/cli/plugins.rb +85 -12
  45. data/lib/kward/cli/prompt_interface.rb +29 -6
  46. data/lib/kward/cli/rendering.rb +24 -28
  47. data/lib/kward/cli/runtime_helpers.rb +168 -56
  48. data/lib/kward/cli/sessions.rb +9 -5
  49. data/lib/kward/cli/settings/menus.rb +745 -0
  50. data/lib/kward/cli/settings/model.rb +316 -0
  51. data/lib/kward/cli/settings.rb +6 -1055
  52. data/lib/kward/cli/slash_commands.rb +45 -4
  53. data/lib/kward/cli/tabs.rb +257 -44
  54. data/lib/kward/cli/tool_summaries.rb +2 -0
  55. data/lib/kward/{cli_transcript_formatter.rb → cli/transcript_formatter.rb} +6 -13
  56. data/lib/kward/cli/worktrees.rb +66 -2
  57. data/lib/kward/cli.rb +82 -31
  58. data/lib/kward/compactor.rb +18 -7
  59. data/lib/kward/config/core.rb +400 -0
  60. data/lib/kward/config/extensions.rb +99 -0
  61. data/lib/kward/config/paths.rb +11 -0
  62. data/lib/kward/config/prompts.rb +313 -0
  63. data/lib/kward/config/settings.rb +257 -0
  64. data/lib/kward/config_files.rb +14 -1008
  65. data/lib/kward/conversation.rb +41 -2
  66. data/lib/kward/entrypoint.rb +14 -0
  67. data/lib/kward/events.rb +2 -0
  68. data/lib/kward/generated_images.rb +237 -0
  69. data/lib/kward/image_attachments.rb +1 -1
  70. data/lib/kward/model/catalog.rb +6 -3
  71. data/lib/kward/model/client.rb +107 -38
  72. data/lib/kward/model/codex_images.rb +83 -0
  73. data/lib/kward/model/copilot_models.rb +10 -6
  74. data/lib/kward/model/model_info.rb +42 -7
  75. data/lib/kward/{openrouter_model_cache.rb → model/openrouter_model_cache.rb} +7 -5
  76. data/lib/kward/model/payloads.rb +18 -8
  77. data/lib/kward/model/sources.rb +3 -1
  78. data/lib/kward/model/stream_parser.rb +4 -7
  79. data/lib/kward/model/typesafe_client.rb +78 -0
  80. data/lib/kward/pan/index.html.erb +8 -1
  81. data/lib/kward/pan/server.rb +23 -8
  82. data/lib/kward/permissions/policy.rb +6 -2
  83. data/lib/kward/plugin_registry.rb +2 -659
  84. data/lib/kward/plugins/actions.rb +453 -0
  85. data/lib/kward/plugins/chat_contract.rb +121 -0
  86. data/lib/kward/{plugin_chat_runtime.rb → plugins/chat_runtime.rb} +62 -18
  87. data/lib/kward/plugins/codex_responses.rb +73 -0
  88. data/lib/kward/plugins/host.rb +248 -0
  89. data/lib/kward/plugins/http_server.rb +83 -0
  90. data/lib/kward/plugins/registry.rb +1229 -0
  91. data/lib/kward/plugins/resources.rb +206 -0
  92. data/lib/kward/plugins/turn_request.rb +36 -0
  93. data/lib/kward/plugins/ui.rb +219 -0
  94. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  95. data/lib/kward/prompt_interface/composer_renderer.rb +160 -73
  96. data/lib/kward/prompt_interface/composer_state.rb +1 -1
  97. data/lib/kward/prompt_interface/editor/controller.rb +2 -2
  98. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  99. data/lib/kward/prompt_interface/editor/runner.rb +1 -1
  100. data/lib/kward/prompt_interface/editor/state.rb +1 -1
  101. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  102. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  103. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  104. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  105. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  106. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  107. data/lib/kward/prompt_interface/layout.rb +11 -1
  108. data/lib/kward/prompt_interface/overlay_renderer.rb +26 -9
  109. data/lib/kward/prompt_interface/plugin_ui_requests.rb +82 -0
  110. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  111. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  112. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  113. data/lib/kward/prompt_interface/runtime_state.rb +37 -10
  114. data/lib/kward/prompt_interface/screen.rb +30 -20
  115. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  116. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  117. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  118. data/lib/kward/prompt_interface.rb +149 -30
  119. data/lib/kward/prompts/commands.rb +2 -1
  120. data/lib/kward/prompts.rb +7 -1
  121. data/lib/kward/{adaptive_pty_output_sink.rb → pty/adaptive_output_sink.rb} +39 -5
  122. data/lib/kward/{interactive_pty_runner.rb → pty/interactive_runner.rb} +22 -30
  123. data/lib/kward/{local_command_runner.rb → pty/local_command_runner.rb} +1 -1
  124. data/lib/kward/{local_pty_command_runner.rb → pty/local_pty_runner.rb} +3 -9
  125. data/lib/kward/{pty_output_sink.rb → pty/output_sink.rb} +9 -4
  126. data/lib/kward/pty/transcript_normalizer.rb +137 -0
  127. data/lib/kward/rpc/config_manager.rb +3 -0
  128. data/lib/kward/rpc/plugin_chat_manager.rb +30 -10
  129. data/lib/kward/rpc/prompt_bridge.rb +25 -0
  130. data/lib/kward/rpc/server.rb +118 -17
  131. data/lib/kward/rpc/session_manager.rb +208 -60
  132. data/lib/kward/rpc/session_tree_rows.rb +2 -2
  133. data/lib/kward/rpc/tool_metadata.rb +1 -1
  134. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  135. data/lib/kward/sandbox/command_runner.rb +1 -1
  136. data/lib/kward/{session_catalog.rb → sessions/catalog.rb} +1 -1
  137. data/lib/kward/{session_store.rb → sessions/store.rb} +39 -12
  138. data/lib/kward/{session_tree_nodes.rb → sessions/tree_nodes.rb} +3 -3
  139. data/lib/kward/{session_tree_renderer.rb → sessions/tree_renderer.rb} +4 -4
  140. data/lib/kward/{session_tree_tool_display.rb → sessions/tree_tool_display.rb} +1 -1
  141. data/lib/kward/{kwsh.rb → shell/kwsh.rb} +30 -10
  142. data/lib/kward/{kwshrc.rb → shell/kwshrc.rb} +11 -2
  143. data/lib/kward/shell/native_arithmetic.rb +255 -0
  144. data/lib/kward/shell/native_arrays.rb +102 -0
  145. data/lib/kward/shell/native_braces.rb +96 -0
  146. data/lib/kward/shell/native_builtins.rb +476 -0
  147. data/lib/kward/shell/native_completion.rb +169 -0
  148. data/lib/kward/shell/native_condition.rb +75 -0
  149. data/lib/kward/shell/native_directory.rb +116 -0
  150. data/lib/kward/shell/native_exec_state.rb +73 -0
  151. data/lib/kward/shell/native_expansion.rb +252 -0
  152. data/lib/kward/shell/native_fields.rb +62 -0
  153. data/lib/kward/shell/native_glob.rb +96 -0
  154. data/lib/kward/shell/native_history.rb +242 -0
  155. data/lib/kward/shell/native_interactive.rb +164 -0
  156. data/lib/kward/shell/native_invocation.rb +42 -0
  157. data/lib/kward/shell/native_jobs.rb +250 -0
  158. data/lib/kward/shell/native_line_editor.rb +382 -0
  159. data/lib/kward/shell/native_line_terminal.rb +286 -0
  160. data/lib/kward/shell/native_locale.rb +109 -0
  161. data/lib/kward/shell/native_locals.rb +57 -0
  162. data/lib/kward/shell/native_pattern.rb +200 -0
  163. data/lib/kward/shell/native_process.rb +279 -0
  164. data/lib/kward/shell/native_program.rb +40 -0
  165. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  166. data/lib/kward/shell/native_prompt_format.rb +89 -0
  167. data/lib/kward/shell/native_runtime.rb +964 -0
  168. data/lib/kward/shell/native_substitution.rb +110 -0
  169. data/lib/kward/shell/native_syntax.rb +946 -0
  170. data/lib/kward/shell/native_traps.rb +196 -0
  171. data/lib/kward/shell/native_vi.rb +407 -0
  172. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  173. data/lib/kward/shell/native_worker.rb +82 -0
  174. data/lib/kward/{persistent_shell_session.rb → shell/persistent_session.rb} +187 -193
  175. data/lib/kward/shell/prompt.rb +66 -0
  176. data/lib/kward/shell/prompt_agent.rb +17 -0
  177. data/lib/kward/{shell_prompt_session.rb → shell/prompt_session.rb} +1 -1
  178. data/lib/kward/shell/script_runner.rb +244 -0
  179. data/lib/kward/shell/standalone_agent.rb +31 -0
  180. data/lib/kward/shell/standalone_link.rb +78 -0
  181. data/lib/kward/shell/standalone_terminal.rb +287 -0
  182. data/lib/kward/skills/trust_store.rb +1 -1
  183. data/lib/kward/tabs/driver.rb +194 -0
  184. data/lib/kward/{tab_store.rb → tabs/store.rb} +2 -2
  185. data/lib/kward/{clipboard.rb → terminal/clipboard.rb} +1 -1
  186. data/lib/kward/{terminal_image_support.rb → terminal/image_support.rb} +1 -1
  187. data/lib/kward/{terminal_keys.rb → terminal/keys.rb} +22 -1
  188. data/lib/kward/terminal/locale_text.rb +29 -0
  189. data/lib/kward/{terminal_sequences.rb → terminal/sequences.rb} +45 -4
  190. data/lib/kward/tools/base.rb +18 -0
  191. data/lib/kward/tools/context_for_task.rb +15 -6
  192. data/lib/kward/tools/datetime.rb +85 -0
  193. data/lib/kward/tools/edit_file.rb +9 -6
  194. data/lib/kward/tools/generate_image.rb +36 -0
  195. data/lib/kward/tools/git_commit.rb +13 -7
  196. data/lib/kward/tools/list_directory.rb +4 -4
  197. data/lib/kward/tools/plugin_tool.rb +41 -0
  198. data/lib/kward/tools/prepare_shell_command.rb +1 -1
  199. data/lib/kward/tools/read_file.rb +7 -6
  200. data/lib/kward/tools/registry.rb +130 -21
  201. data/lib/kward/tools/run_shell_command.rb +10 -8
  202. data/lib/kward/tools/search/code.rb +1 -1
  203. data/lib/kward/tools/summarize_file_structure.rb +5 -5
  204. data/lib/kward/tools/tool_call.rb +4 -1
  205. data/lib/kward/tools/typesafe_evaluate.rb +81 -0
  206. data/lib/kward/tools/workspace_targets.rb +58 -0
  207. data/lib/kward/tools/write_file.rb +9 -6
  208. data/lib/kward/{export_path.rb → transcripts/export_path.rb} +1 -1
  209. data/lib/kward/{markdown_transcript.rb → transcripts/markdown_transcript.rb} +10 -2
  210. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  211. data/lib/kward/transport/contracts.rb +200 -0
  212. data/lib/kward/transport/gateway.rb +81 -36
  213. data/lib/kward/transport/plugin_chat_gateway.rb +3 -2
  214. data/lib/kward/transport.rb +1 -200
  215. data/lib/kward/turn_summary.rb +68 -0
  216. data/lib/kward/version.rb +1 -1
  217. data/lib/kward/{workspace_factory.rb → workspace/factory.rb} +2 -2
  218. data/lib/kward/{git_worktree_manager.rb → workspace/git_worktree_manager.rb} +28 -0
  219. data/lib/kward/{workspace.rb → workspace/workspace.rb} +3 -3
  220. data/lib/main.rb +6 -3
  221. data/templates/default/fulldoc/html/css/kward.css +125 -0
  222. data/templates/default/fulldoc/html/images/kward_screen_1.png +0 -0
  223. data/templates/default/fulldoc/html/setup.rb +1 -1
  224. data/templates/default/layout/html/layout.erb +16 -4
  225. metadata +150 -48
  226. data/lib/kward/pty_transcript_normalizer.rb +0 -93
  227. data/lib/kward/shell_prompt.rb +0 -52
  228. data/lib/kward/tab_driver.rb +0 -90
  229. data/templates/default/fulldoc/html/images/kward_workflow.svg +0 -52
  230. /data/lib/kward/{editor_prompt.rb → cli/editor_prompt.rb} +0 -0
  231. /data/lib/kward/{editor_prompt_session.rb → cli/editor_prompt_session.rb} +0 -0
  232. /data/lib/kward/{diff_view_mode.rb → prompt_interface/editor/diff_view_mode.rb} +0 -0
  233. /data/lib/kward/{editor_mode.rb → prompt_interface/editor/editor_mode.rb} +0 -0
  234. /data/lib/kward/{markdown_code_block.rb → prompt_interface/editor/markdown_code_block.rb} +0 -0
  235. /data/lib/kward/{scratchpad_languages.rb → prompt_interface/editor/scratchpad_languages.rb} +0 -0
  236. /data/lib/kward/{scratchpad_runner.rb → prompt_interface/editor/scratchpad_runner.rb} +0 -0
  237. /data/lib/kward/{detached_run.rb → pty/detached_run.rb} +0 -0
  238. /data/lib/kward/{session_diff.rb → sessions/diff.rb} +0 -0
  239. /data/lib/kward/{session_naming.rb → sessions/naming.rb} +0 -0
  240. /data/lib/kward/{session_trash.rb → sessions/trash.rb} +0 -0
  241. /data/lib/kward/{ansi.rb → terminal/ansi.rb} +0 -0
  242. /data/lib/kward/{terminal_text.rb → terminal/text.rb} +0 -0
  243. /data/lib/kward/{transcript_export.rb → transcripts/transcript_export.rb} +0 -0
  244. /data/lib/kward/{project_files.rb → workspace/files.rb} +0 -0
  245. /data/lib/kward/{path_guard.rb → workspace/path_guard.rb} +0 -0
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 10d9376091daae14fa22ee39099645cb78bbdb8ff8de89a5982ffe2929396d67
4
- data.tar.gz: 633ec7446e83664c18fcac2a12fcdf686dcc81cf21fc33cf73026186b4765540
3
+ metadata.gz: d5f437e5a636602d7742b14f118fd9232cc518c4b796089ae069b6a26edbb276
4
+ data.tar.gz: 135a464bab9b9c844940739243545d5c05a786a4b9757debc001e621b25e6bb7
5
5
  SHA512:
6
- metadata.gz: '01750111663180d8f89afe2e2bfc7e14ada0c5942621d0ac5cc74eddda07db81d164ea6b3c55fbb6d3082b9e76834cb74094807bba67ac1419f06c68453e595c'
7
- data.tar.gz: f4e8e96278bd737a4912461325381e63477d52a4a1710ea53b0c08ce7aeb2caba88a2662f1a8a8d24b8d7e339d745f1ece1816626c4f7e142aeac9e0cdd0cc15
6
+ metadata.gz: 59254bfcee2caf48063b513dd78f1135edaadb4bbb39eb1dc8d929943398e9f60cf60df600d4d588ec854885607d60a1ad1322f689b9e7e3fd06e5108971d733
7
+ data.tar.gz: 993c21c4ba06234d834c72e64c81093d70c5bbbfcb0db04cb4d9c98471b4d9c4a210a6d61733ab6bb76cfc138cc5c54172fe5e934c034baa1da2dc4d4e85f545
data/CHANGELOG.md CHANGED
@@ -4,6 +4,169 @@ 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
+
137
+ ## [0.85.0] - 2026-10-05
138
+
139
+ ### Added
140
+
141
+ - Added the opt-in `typesafe_evaluate` tool backed by TypeSafe's Jev structured-decision API for `noul`, `choice`, and `score` evaluations, with bounded input and normal tool permissions.
142
+ - Added `ctx.request_turn(system: text)` for plugin commands to run the active session model with turn-scoped system instructions, normal tools and cancellation, TUI/RPC/transport execution, persisted invocation history, and explicit capability reporting for unsupported contexts.
143
+ - Added GPT-6 Astra to the OpenAI, Codex, and Copilot model choices with its 1,050,000-token context metadata and model-specific reasoning limits.
144
+ - Added GPT-6.1 Sol and GPT-6 Luna to the OpenAI model choices with their 1,050,000-token context metadata and model-specific reasoning limits.
145
+ - Added verified `active` and `origin` targets to core agent workspace tools in linked worktree tabs, plus same-tab merge conflict resolution and continuation commands, allowing the agent to inspect, resolve, test, and complete original-worktree merges without switching tabs or requiring target-specific authorization.
146
+ - Added a versioned plugin-chat contract with declared attachment, steering, and transcript-paging capabilities; scoped chat configuration/storage/secrets/logging; surface and scope context; persistent local scope IDs; RPC capability discovery; and driver validation while preserving legacy plugin tabs.
147
+ - Added composable plugin footer status with stable segment IDs, display ordering, width-aware priority removal, isolated render failures, structured RPC segments and tooltips, and backward-compatible `plugin.footer` contributions.
148
+ - Added identified-plugin start, reload, and shutdown callbacks; plugin- and tab-owned cooperative background tasks; idempotent managed cleanup; bounded shutdown waits; and optional plugin-tab driver cleanup.
149
+ - Added typed plugin commands with JSON Schema validation, shell-style flags and declared positional arguments, structured frontend/RPC results, cancellation context, and legacy raw-string compatibility, plus identified-plugin actions with namespaced RPC discovery and execution.
150
+ - Added structured frontend-neutral plugin UI for questions, selections, confirmations, text input, progress, and notifications, with TUI rendering, RPC capability negotiation and request/answer notifications, transport interaction routing, bounded validation, cancellation, and fail-closed fallbacks.
151
+ - Added stable plugin identity metadata and a shared plugin host with namespaced configuration, private durable storage, secret lookup, logging, API compatibility checks, and sanitized RPC discovery.
152
+ - Added model-callable plugin tools with strict JSON schemas, cancellation context, normal permission and lifecycle-hook enforcement, execution-profile filtering, RPC discovery, and tool-output compaction.
153
+ - Added `/name` to rename the active session and tab together, including while the tab's agent is running.
154
+
155
+ ### Changed
156
+
157
+ - Grouped session, shell, PTY, terminal, workspace, plugin, tab, transcript, editor, and model implementations under domain folders and removed the old internal require paths.
158
+
159
+ ### Fixed
160
+
161
+ - Fixed plugin system-turn instructions being folded into the old conversation's preamble instead of appearing as a new ordered message; Codex uses its supported `developer` input role, while direct OpenAI uses `system`.
162
+ - Fixed plugin system-turn commands such as `/iddqd` crashing in the TUI image renderer; system instructions render as plain text without attachment parsing.
163
+ - Fixed the documentation homepage’s `Get Started` link so it opens the getting-started guide.
164
+ - Fixed the interactive composer leaving the final streamed transcript line too close to its top border.
165
+ - Fixed `/compact` completion output and cancellation so work remains owned by its originating tab instead of rendering into whichever tab is active.
166
+ - Fixed detached `/shell` commands losing output across tab switches by retaining pre-detach output and streaming buffered output when the originating tab is active again.
167
+ - Fixed interactive PTY handoff cleanup so preserved keyboard protocol state is reasserted only after a child reset and remains balanced when Kward exits.
168
+ - Fixed `/rewind` and session-tree navigation detaching active worktree tabs by reloading their conversations against the original workspace instead of the linked worktree.
169
+
7
170
  ## [0.84.0] - 2026-08-30
8
171
 
9
172
  ### Added
@@ -32,6 +195,7 @@ All notable changes to Kward will be documented in this file.
32
195
  - Added unobtrusive elapsed-time feedback after two seconds, final turn duration in completion transitions, and provider-reported tool durations in result summaries.
33
196
  - Added stable `❯` user and `✦` assistant anchors to make transcript turn boundaries easier to scan without changing stored conversation content.
34
197
  - Added persistent background-tab status colors for running work, unread output, successful detached commands, questions, and failures without changing tab label widths.
198
+ - Restored green for ready tabs with unread output.
35
199
  - Documentation checks now validate the curated public extension entry points without presenting aggregate internal-helper coverage as a product-quality metric.
36
200
  - The repository and documentation landing pages now use a focused coding-workflow visual, restrained project badges, and clearer product identity.
37
201
  - Updated RubyGems positioning and metadata to describe Kward's supported product surfaces and direct users to the documentation site while keeping source and issue links on GitHub.
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.84.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.84.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
@@ -25,7 +25,7 @@ Kward treats that work as an ongoing workspace rather than a disposable conversa
25
25
  Start with a normal coding conversation. If your workflow grows, you can add memory, reusable prompts and skills, local plugins, lifecycle hooks, MCP servers, transports, or a custom RPC client.
26
26
 
27
27
  <p align="center">
28
- <img src="templates/default/fulldoc/html/images/kward_workflow.svg" width="1000" alt="Kward completing a focused coding change and test run">
28
+ <img src="templates/default/fulldoc/html/images/kward_screen_1.png" width="1000" alt="Kward terminal interface screenshot">
29
29
  </p>
30
30
 
31
31
  ## Install
@@ -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.
@@ -127,7 +127,7 @@ Generated Ruby API:
127
127
 
128
128
  ## Development
129
129
 
130
- Read [Contributing to Kward](https://github.com/kaiwood/kward/blob/main/CONTRIBUTING.md) before preparing a pull request. Participation is governed by the [Code of conduct](https://github.com/kaiwood/kward/blob/main/CODE_OF_CONDUCT.md).
130
+ Read [Contributing to Kward](https://github.com/kaiwood/kward/blob/main/CONTRIBUTING.md) before preparing a pull request.
131
131
 
132
132
  Run tests:
133
133
 
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,7 +18,19 @@ 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) |
23
+ | Decision tools | `typesafe_evaluate` when `TYPESAFE_API_KEY` is configured | [TypeSafe](#TypeSafe_evaluation) |
24
+ | Plugin tools | Trusted local integrations registered by installed plugins | [Plugins](plugins.md#Add_a_model_callable_tool) |
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.
22
34
 
23
35
  ## How tools save tokens
24
36
 
@@ -42,7 +54,18 @@ See [Context budgeting](context-budgeting.md) for the full compaction strategy,
42
54
 
43
55
  - web tools can be hidden with web search configuration,
44
56
  - `read_skill` is advertised only when skills are available,
45
- - `ask_user_question` is advertised only when the frontend can display structured questions.
57
+ - `ask_user_question` is advertised only when the frontend can display structured questions,
58
+ - `typesafe_evaluate` is advertised only in normal turns when `TYPESAFE_API_KEY` is configured,
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.
61
+
62
+ ### TypeSafe evaluation
63
+
64
+ Set `TYPESAFE_API_KEY` to enable the opt-in `typesafe_evaluate` tool. It sends explicitly supplied state and typed questions to TypeSafe's `jev-latest` model and returns structured answers, probabilities, confidence, and usage. It is intended for classification, scoring, routing, and verification; it is not a chat model and does not generate assistant text.
65
+
66
+ The tool supports TypeSafe's `noul`, `choice`, and `score` question types. State is bounded to 100,000 bytes and question count to 100. Treat state as third-party data: do not include secrets or personal information unless sending it to TypeSafe is intentional. Requests remain subject to Kward's normal tool permissions and hooks.
67
+
68
+ See the [TypeSafe API reference](https://docs.typesafe.ai/api) for question and answer details.
46
69
 
47
70
  When `write_file` or `edit_file` changes an `AGENTS.md` file in the workspace root, Kward automatically rebuilds the system message so the model picks up the new instructions without a restart.
48
71
 
data/doc/api.md CHANGED
@@ -15,7 +15,12 @@ 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 slash commands, prompt context, footer UI, transcript events, or RPC-visible commands.
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
+
20
+ Session commands can stage a host-owned model response with
21
+ `ctx.request_turn(system: text)`; check `ctx.turn_requests_supported?` before
22
+ offering this on an unknown frontend. Instructions are scoped to that turn,
23
+ while normal tools, hooks, cancellation, and session history remain host-owned.
19
24
 
20
25
  Read first:
21
26
 
@@ -28,6 +33,19 @@ Generated entry points:
28
33
  - [`Kward::PluginRegistry`](Kward/PluginRegistry.html)
29
34
  - [`Kward::PluginRegistry::DSL`](Kward/PluginRegistry/DSL.html)
30
35
  - [`Kward::PluginRegistry::Context`](Kward/PluginRegistry/Context.html)
36
+ - [`Kward::PluginCommand`](Kward/PluginCommand.html)
37
+ - [`Kward::PluginAction`](Kward/PluginAction.html)
38
+ - [`Kward::PluginResult`](Kward/PluginResult.html)
39
+ - [`Kward::PluginRegistry::DSL#startup_option`](Kward/PluginRegistry/DSL.html#startup_option-instance_method)
40
+ - [`Kward::PluginHost`](Kward/PluginHost.html)
41
+ - [`Kward::PluginHTTPServer`](Kward/PluginHTTPServer.html)
42
+ - [`Kward::PluginCodexResponses`](Kward/PluginCodexResponses.html)
43
+ - [`Kward::PluginStore`](Kward/PluginStore.html)
44
+ - [`Kward::PluginScopedStore`](Kward/PluginScopedStore.html)
45
+ - [`Kward::PluginChatCapabilities`](Kward/PluginChatCapabilities.html)
46
+ - [`Kward::PluginTask`](Kward/PluginTask.html)
47
+ - [`Kward::PluginDisposable`](Kward/PluginDisposable.html)
48
+ - [`Kward::PluginTabHost`](Kward/PluginTabHost.html)
31
49
 
32
50
  ### Tool authors and contributors
33
51
 
@@ -45,7 +63,7 @@ Generated entry points:
45
63
  - [`Kward::Tools::Base`](Kward/Tools/Base.html)
46
64
  - [`Kward::ToolRegistry`](Kward/ToolRegistry.html)
47
65
 
48
- These pages document the schema and dispatch contract used by built-in tools. Kward does not yet provide a plugin DSL for registering arbitrary model-callable tools; contributors add them through the built-in registry and keep schemas, validation, docs, and tests aligned.
66
+ These pages document the schema and dispatch contract used by built-in tools. Plugin authors can register model-callable tools through `PluginRegistry::DSL#tool`; those tools use the same permission, lifecycle-hook, execution-profile, and output-compaction path.
49
67
 
50
68
  ### RPC and frontend authors
51
69
 
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
 
@@ -197,7 +198,7 @@ The composer area can include:
197
198
  - approximate context-window usage,
198
199
  - provider, model, and reasoning effort,
199
200
  - a tab bar plus queued or steered input counts,
200
- - an optional plugin footer.
201
+ - composable status contributions from installed plugins.
201
202
 
202
203
  Context usage is an estimate, not provider billing. Use `/status` for more session and compaction detail.
203
204
 
data/doc/configuration.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Kward reads user configuration from `~/.kward/config.json` by default. Most users should start with `/settings`, `/login`, `/model`, or `/reasoning` inside Kward. Edit JSON directly when you need an advanced setting, an integration, or a reproducible configuration.
4
4
 
5
- On first start, Kward creates the file when it does not exist. The starter config records defaults for personas, memory, the composer, editor, overlays, web search, update checks, sessions, skills, MCP, and workspace guardrails. Provider-specific model defaults are added only when you choose a provider or model.
5
+ On first start, Kward creates the file when it does not exist. The starter config records defaults for personas, memory, the composer, editor, overlays, web search, update checks, sessions, skills, MCP, plugins, and workspace guardrails. Provider-specific model defaults are added only when you choose a provider or model.
6
6
 
7
7
  If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as the config directory for prompts, skills, memory, logs, and caches.
8
8
 
@@ -50,6 +50,27 @@ Add trusted local Model Context Protocol servers under `mcpServers`:
50
50
 
51
51
  See [MCP servers](mcp.md) for setup, supported fields, and security notes.
52
52
 
53
+ ### Plugin configuration
54
+
55
+ Identified plugins read immutable configuration from the `plugins` object under
56
+ their stable ID:
57
+
58
+ ```json
59
+ {
60
+ "plugins": {
61
+ "com.example.issues": {
62
+ "endpoint": "https://issues.example.com"
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ Plugin-managed state is stored privately under `plugin_state/<plugin-id>` in the
69
+ active config directory. Credentials can come from private plugin config or the
70
+ plugin's documented environment variables; do not commit them to shared config
71
+ files. See [Plugins](plugins.md#Plugin_identity_and_host_services) for the host
72
+ API, secret lookup order, and storage example.
73
+
53
74
  ### Transport plugins
54
75
 
55
76
  Transport plugin settings live under `transports` and are scoped by the
@@ -167,11 +188,11 @@ Use `failure_policy` (`allow`, `warn`, `deny`, or `ask`) to decide what happens
167
188
 
168
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.
169
190
 
170
- ## Embedded shell config
191
+ ## Shell configuration
171
192
 
172
- 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.
173
194
 
174
- Example rc file:
195
+ For settings shared with `/shell` and leading-`!` commands, stick to declarative directives:
175
196
 
176
197
  ```sh
177
198
  alias ll='ls -la'
@@ -181,11 +202,11 @@ export PATH="$HOME/bin:$PATH"
181
202
  source ~/.kward/kwsh-aliases
182
203
  ```
183
204
 
184
- 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.
185
206
 
186
207
  ### Shell-agent model
187
208
 
188
- 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:
189
210
 
190
211
  ```json
191
212
  {
@@ -199,9 +220,9 @@ The transient shell assistant normally follows the active conversation's model a
199
220
  }
200
221
  ```
201
222
 
202
- 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.
203
224
 
204
- Environment variables take precedence over the JSON settings:
225
+ Environment variables exported before launching Kward take precedence over the JSON settings:
205
226
 
206
227
  ```sh
207
228
  export KWSH_PROVIDER="openrouter"
@@ -211,9 +232,9 @@ export KWSH_REASONING="none"
211
232
 
212
233
  `KWSH_PROVIDER` selects the shell-agent provider, `KWSH_MODE` selects its model, and `KWSH_REASONING` selects its reasoning effort. Empty values are ignored.
213
234
 
214
- `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.
215
236
 
216
- `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.
217
238
 
218
239
  ## Provider and model settings
219
240
 
@@ -263,7 +284,7 @@ Model settings:
263
284
 
264
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.
265
286
 
266
- 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.
267
288
 
268
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.
269
290
 
@@ -275,6 +296,8 @@ Defaults:
275
296
  - Copilot: `gpt-5-mini`
276
297
  - Reasoning effort: `medium`
277
298
 
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
+
278
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.
279
302
 
280
303
  The interactive `/model` picker reads cached OpenRouter models when available. Run `kward openrouter refresh` to fetch text-capable models available to the configured OpenRouter API key and cache them under `~/.kward/cache/openrouter_models.json`. Run `kward openrouter list` to inspect the cached model ids.
@@ -406,6 +429,55 @@ In the normal composer prompt, choose reasoning effort with `/reasoning` or `/mo
406
429
 
407
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.
408
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
+
409
481
  ## Editor settings
410
482
 
411
483
  The built-in TUI file editor supports three keybinding modes. Modern is the default:
@@ -728,9 +800,9 @@ Available modes are:
728
800
 
729
801
  | Mode | Behavior |
730
802
  | --- | --- |
731
- | `ask` | Read-only tools run normally; file changes, shell commands, web tools, and MCP tools need approval. |
732
- | `workspace-write` | File changes within `write_scopes` run without approval; shell and network tools still need approval. |
733
- | `read-only` | Denies file changes, shell commands, web tools, and MCP tools. |
803
+ | `ask` | Read-only tools run normally; file changes, shell commands, web tools, MCP tools, and plugin tools need approval. |
804
+ | `workspace-write` | File changes within `write_scopes` run without approval; shell, network, MCP, and plugin tools still need approval. |
805
+ | `read-only` | Denies file changes, shell commands, web tools, MCP tools, and plugin tools. |
734
806
  | `deny-by-default` | Denies risky tools unless an `allow` rule matches. |
735
807
 
736
808
  `allow`, `ask`, and `deny` rules are arrays of objects matching `tool`, `path`, `host`, `command`, or `source`. Deny rules always take precedence, then ask, then allow. Use `write_scopes` to restrict writes in `workspace-write` mode: