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
data/doc/plugins.md CHANGED
@@ -5,6 +5,7 @@ Plugins are trusted local Ruby extensions for Kward. Use them when you need beha
5
5
  Good plugin use cases:
6
6
 
7
7
  - add a slash command for a personal workflow,
8
+ - expose a local integration as a model-callable tool,
8
9
  - show project/session status in the terminal footer,
9
10
  - add concise local context to prompts,
10
11
  - log or observe transcript events,
@@ -21,7 +22,7 @@ Plugins run inside the Kward process with your user permissions. Install only pl
21
22
  | Repository rules | `AGENTS.md` |
22
23
  | Local Ruby code or integration | plugin |
23
24
 
24
- 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.
25
26
 
26
27
  ## Where plugins live
27
28
 
@@ -49,7 +50,7 @@ mkdir -p ~/.kward/plugins
49
50
  Create `~/.kward/plugins/hello.rb`:
50
51
 
51
52
  ```ruby
52
- Kward.plugin do |plugin|
53
+ Kward.plugin(id: "com.example.hello", version: "1.0.0", api: 1) do |plugin|
53
54
  plugin.command "hello", description: "Say hello", argument_hint: "[name]" do |args, ctx|
54
55
  name = args.strip.empty? ? "there" : args.strip
55
56
  ctx.say("Hello, #{name}.")
@@ -65,6 +66,146 @@ Start Kward and run:
65
66
 
66
67
  When developing plugins or prompt templates, use `/reload` inside Kward to reload configured prompt files and all plugin files without restarting. This picks up prompt edits, changes to existing plugins, and new plugin registrations, then refreshes slash-command completion and rebuilds the system message.
67
68
 
69
+ ## Plugin identity and host services
70
+
71
+ Give a reusable plugin a stable reverse-domain-style `id`, its own `version`, and
72
+ the Kward plugin API it targets. API version `1` is currently supported. Kward
73
+ skips plugins that declare an unsupported API version or duplicate another
74
+ plugin's ID.
75
+
76
+ An identified plugin receives one shared host for configuration, private durable
77
+ storage, secret lookup, and logging:
78
+
79
+ ```ruby
80
+ Kward.plugin(id: "com.example.issues", version: "1.2.0", api: 1) do |plugin|
81
+ host = plugin.host
82
+
83
+ plugin.command "issue-server", description: "Show the issue server" do |_args, ctx|
84
+ visits = host.storage.get("visits").to_i + 1
85
+ endpoint = host.config.fetch("endpoint")
86
+ host.storage.put("visits", visits)
87
+ ctx.say("#{endpoint} (visit #{visits})")
88
+ end
89
+ end
90
+ ```
91
+
92
+ Configure the plugin under its stable ID in `config.json`:
93
+
94
+ ```json
95
+ {
96
+ "plugins": {
97
+ "com.example.issues": {
98
+ "endpoint": "https://issues.example.com"
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ The host exposes:
105
+
106
+ - `host.id`, `host.version`, and `host.api_version`;
107
+ - `host.config`, an immutable copy of the plugin's namespaced configuration;
108
+ - `host.storage.get`, `put`, and `delete` for JSON-compatible values;
109
+ - `host.secret(name, env: nil)` for private config or environment lookup;
110
+ - `host.logger`, a standard Ruby logger routed through Kward's diagnostic output.
111
+
112
+ Storage is kept in `plugin_state/<plugin-id>/state.json` under Kward's active
113
+ config directory and survives `/reload`. Secret lookup checks plugin config,
114
+ then the optional explicit environment variable, then a conventional name such
115
+ as `KWARD_PLUGIN_COM_EXAMPLE_ISSUES_TOKEN`. Do not log secret values.
116
+
117
+ Existing `Kward.plugin do ... end` files remain supported, but `plugin.host` is
118
+ `nil` until the plugin declares stable identity metadata.
119
+
120
+ ## Lifecycle and owned background work
121
+
122
+ Plugin files are loaded without starting runtime work. Identified plugins can
123
+ register lifecycle callbacks for the points where managed work is safe:
124
+
125
+ ```ruby
126
+ Kward.plugin(id: "com.example.watcher", version: "1.0.0", api: 1) do |plugin|
127
+ plugin.on_start do |host|
128
+ subscription = Watcher.subscribe { |event| host.logger.info(event) }
129
+ host.on_cleanup(subscription) { |value| Watcher.unsubscribe(value) }
130
+
131
+ host.background(name: "poller") do |cancellation|
132
+ until cancellation.cancelled?
133
+ Watcher.poll
134
+ sleep 1
135
+ end
136
+ end
137
+ end
138
+
139
+ plugin.on_reload { |host| host.logger.info("Reloading") }
140
+ plugin.on_shutdown { |host| host.logger.info("Stopping") }
141
+ end
142
+ ```
143
+
144
+ Lifecycle behavior is explicit:
145
+
146
+ - `on_start` runs after loading, when the registry becomes active. A newly loaded
147
+ registry receives `on_start` after `/reload` too.
148
+ - `on_reload` runs on the old plugin instance immediately before Kward cleans up
149
+ its resources.
150
+ - `on_shutdown` runs immediately before final process cleanup.
151
+ - Callback failures are reported as warnings and do not prevent other plugins
152
+ from cleaning up.
153
+
154
+ `host.background` returns a `PluginTask`. Its block may accept a cooperative
155
+ `Cancellation` token. Kward cancels and waits up to a bounded deadline for owned
156
+ tasks during reload or shutdown; blocking work should register cleanup that
157
+ closes the socket, stream, or other resource needed to wake it. Tasks also accept
158
+ an optional parent token with `cancellation:`.
159
+
160
+ `host.on_cleanup(resource) { |resource| ... }` returns an idempotent
161
+ `PluginDisposable`. Call `dispose` to unsubscribe early, or leave it registered
162
+ for automatic cleanup. `host.manage` is an alias. Cleanup runs in reverse
163
+ registration order so dependent resources unwind predictably.
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
+
180
+ Plugin-owned tab hosts expose the same `background`, `on_cleanup`, and `manage`
181
+ methods. Their resources are cleaned up when a local tab closes or its shared
182
+ plugin-chat runtime shuts down. A tab driver may implement `close` (or `shutdown`
183
+ as a fallback) for its own final cleanup; Kward invokes it before closing the tab
184
+ host.
185
+
186
+ Do not open network connections or start threads directly while the plugin file
187
+ is loading. Register them from `on_start`, a command, or a plugin-tab factory so
188
+ Kward can own their lifetime.
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
+
68
209
  ## Add a slash command
69
210
 
70
211
  Use plugin commands for local actions that should not call the model.
@@ -82,6 +223,264 @@ Command names do not include `/`. They must start with a letter or number and ma
82
223
 
83
224
  A plugin command cannot replace a built-in command or prompt-template command.
84
225
 
226
+ ### Typed command arguments and results
227
+
228
+ Add an object JSON Schema when a command needs validated arguments. Interactive
229
+ slash commands use shell-style `--flags`; RPC clients may send either the same
230
+ text or an argument object. Declare `positionals:` when selected properties may
231
+ be supplied without flags:
232
+
233
+ ```ruby
234
+ Kward.plugin(id: "com.example.release", version: "1.0.0", api: 1) do |plugin|
235
+ plugin.command "deploy",
236
+ description: "Deploy a service",
237
+ argument_hint: "SERVICE [--environment NAME] [--dry-run]",
238
+ schema: {
239
+ type: "object",
240
+ properties: {
241
+ service: { type: "string" },
242
+ environment: {
243
+ type: "string",
244
+ enum: %w[staging production],
245
+ default: "staging"
246
+ },
247
+ dry_run: { type: "boolean", default: false },
248
+ labels: { type: "array", items: { type: "string" } }
249
+ },
250
+ required: ["service"]
251
+ },
252
+ positionals: ["service"] do |args, ctx|
253
+ deployment = Release.deploy(
254
+ args.fetch("service"),
255
+ environment: args.fetch("environment"),
256
+ dry_run: args.fetch("dry_run"),
257
+ labels: args.fetch("labels", [])
258
+ )
259
+ ctx.result(
260
+ message: "Queued deployment #{deployment.id}.",
261
+ data: { deployment_id: deployment.id }
262
+ )
263
+ end
264
+ end
265
+ ```
266
+
267
+ For example:
268
+
269
+ ```text
270
+ /deploy api --environment production --dry-run --labels urgent --labels "release candidate"
271
+ ```
272
+
273
+ Typed command handlers receive a string-keyed argument hash through both the
274
+ first block argument and `ctx.args`. Supported property types are `string`,
275
+ `integer`, `number`, `boolean`, `array`, and `object`; array items must be scalar.
276
+ Use `--flag` or `--no-flag` for booleans, repeat an array option to collect
277
+ values, and use `--` before positional text that starts with a dash. Unknown,
278
+ missing, duplicate, incorrectly typed, and out-of-enum arguments are rejected
279
+ before plugin code runs. Commands without `schema:` keep receiving their raw
280
+ argument string for compatibility.
281
+
282
+ `ctx.result(message:, data:)` returns optional user-facing text plus optional
283
+ JSON-compatible machine data. The TUI displays `message`. RPC returns the full
284
+ structured result, and asynchronous slash-command turns also emit a
285
+ `pluginCommandResult` event before their normal answer event.
286
+
287
+ ## Add a namespaced action
288
+
289
+ Actions are typed operations intended for trusted RPC integrations rather than
290
+ slash-command completion. They require identified plugin metadata and receive a
291
+ stable `<plugin-id>/<action-name>` ID:
292
+
293
+ ```ruby
294
+ Kward.plugin(id: "com.example.release", version: "1.0.0", api: 1) do |plugin|
295
+ plugin.action "status",
296
+ description: "Read deployment status",
297
+ schema: {
298
+ type: "object",
299
+ properties: { deployment_id: { type: "integer" } },
300
+ required: ["deployment_id"]
301
+ } do |args, ctx|
302
+ deployment = Release.find(args.fetch("deployment_id"))
303
+ ctx.result(data: { id: deployment.id, state: deployment.state })
304
+ end
305
+ end
306
+ ```
307
+
308
+ RPC clients discover actions with `pluginActions/list` and invoke them with
309
+ `pluginActions/run`. Action arguments must be an object and results always use
310
+ the structured `{ message, data }` contract. Synchronous actions support
311
+ `ctx.say`, progress, and notifications, but blocking UI requests fail closed so
312
+ the RPC reader cannot deadlock. Actions are disabled when the session execution
313
+ profile disables plugin commands. They are not exposed as local TUI commands;
314
+ register a typed command as well when people should invoke the operation from
315
+ the composer.
316
+
317
+ ## Add a model-callable tool
318
+
319
+ Plugin tools let the model call trusted local Ruby integrations without requiring
320
+ an MCP server. Define a model-facing description and a strict object JSON Schema
321
+ for the arguments:
322
+
323
+ ```ruby
324
+ Kward.plugin do |plugin|
325
+ plugin.tool "issue_search",
326
+ description: "Search the local issue tracker",
327
+ schema: {
328
+ type: "object",
329
+ properties: {
330
+ query: { type: "string", description: "Issue search text." },
331
+ limit: { type: "integer", description: "Maximum results." }
332
+ },
333
+ required: ["query"]
334
+ } do |args, ctx|
335
+ ctx.cancellation&.raise_if_cancelled!
336
+ IssueTracker.search(args.fetch("query"), limit: args.fetch("limit", 10))
337
+ .map { |issue| "#{issue.id}: #{issue.title}" }
338
+ .join("\n")
339
+ end
340
+ end
341
+ ```
342
+
343
+ The handler receives a parsed argument hash and a normal plugin context. It
344
+ should return model-facing text. `ctx.cancellation` contains the
345
+ active cooperative cancellation token, and `ctx.cancelled?` is a convenient
346
+ boolean check for longer operations.
347
+
348
+ Plugin tool schemas are exposed in normal CLI, RPC, Pan, and transport-backed
349
+ agent turns. Kward forces `additionalProperties: false`, validates required
350
+ property names, reports the tool source as `plugin`, and routes execution through
351
+ the normal permission policy, approval bridge, lifecycle hooks, output
352
+ compaction, and transcript artifact storage. Restricted execution profiles can
353
+ filter plugin tools by name or remove all tools. Editor-scoped prompts,
354
+ shell-agent prompts, and strict worktree agents do not receive plugin tools.
355
+ Plugin-owned chats continue to own their own tool behavior.
356
+
357
+ Plugin tools cannot replace built-in, MCP, or other plugin tools. Duplicate
358
+ plugin registrations are skipped with a warning. Because trusted plugin code can
359
+ perform arbitrary local or network effects, an enabled permission policy treats
360
+ plugin tools as approval-requiring operations unless an explicit allow rule
361
+ matches the tool or `source: plugin`.
362
+
363
+ ## Use structured plugin UI
364
+
365
+ Plugin commands and model-callable plugin tools receive `ctx.ui`, a
366
+ frontend-neutral interface for questions, choices, confirmation, text input,
367
+ notifications, and progress:
368
+
369
+ ```ruby
370
+ plugin.command "release", description: "Prepare a release" do |_args, ctx|
371
+ environment = ctx.ui.select(
372
+ "Environment",
373
+ [
374
+ { label: "Staging", value: "staging", description: "Deploy for testing." },
375
+ { label: "Production", value: "production", description: "Deploy publicly." }
376
+ ]
377
+ )
378
+ next unless environment
379
+ next unless ctx.ui.confirm("Release", "Deploy to #{environment}?")
380
+
381
+ tag = ctx.ui.input("Release tag", "For example, v1.2.0")
382
+ next if tag.to_s.empty?
383
+
384
+ ctx.ui.progress(id: "release", message: "Preparing #{tag}", percent: 25)
385
+ # Perform work here.
386
+ ctx.ui.progress(id: "release", message: "Prepared #{tag}", percent: 100, done: true)
387
+ ctx.ui.notify("#{tag} is ready for #{environment}.", level: :success)
388
+ end
389
+ ```
390
+
391
+ Available methods:
392
+
393
+ - `ctx.ui.question(questions)` uses the same validated 1-4 question contract as
394
+ `ask_user_question` and returns its answer array or `nil` when cancelled;
395
+ - `ctx.ui.select(title, options, message: nil)` accepts 1-100 strings or
396
+ `{ label:, value:, description: }` objects and returns the selected value;
397
+ - `ctx.ui.confirm(title, message = nil, default: false)` returns a boolean;
398
+ - `ctx.ui.input(title, placeholder = nil, default: nil)` returns text or `nil`;
399
+ - `ctx.ui.progress(id:, message:, percent: nil, done: false)` publishes a
400
+ non-blocking progress update;
401
+ - `ctx.ui.notify(message, level: :info)` publishes an `info`, `success`,
402
+ `warning`, or `error` notification;
403
+ - `ctx.ui.supported?(:select)` and `ctx.ui.capabilities` let a plugin inspect
404
+ the active frontend before requesting interaction.
405
+
406
+ Blocking requests fail closed when the active frontend does not support them:
407
+ questions, selections, and input return `nil`, while confirmation returns
408
+ `false`. Notifications and progress fall back to normal `ctx.say` text. Inputs
409
+ and emitted text are bounded, and plugin-tool cancellation is checked before
410
+ and after blocking requests.
411
+
412
+ The interactive terminal implements all six primitives. RPC implements them for
413
+ plugin commands submitted through `turns/start` and for plugin tools; use that
414
+ asynchronous turn path when a command needs to wait for UI input. Synchronous
415
+ RPC `commands/run` supports notifications and progress but deliberately fails
416
+ closed for blocking requests so the protocol reader cannot deadlock waiting for
417
+ its own response. Pan has no interaction bridge, so blocking requests fail
418
+ closed and non-blocking output falls back to its existing plugin message event.
419
+ Transport gateways expose blocking requests as transport-neutral interactions;
420
+ the transport adapter decides whether and how to render and answer them.
421
+
422
+ ## Request a model response from a command
423
+
424
+ Use `ctx.request_turn(system: text)` when a slash command should run the active
425
+ session's model immediately with turn-scoped system instructions. For example,
426
+ save this as `~/.kward/plugins/iddqd.rb` and run `/reload`:
427
+
428
+ ```ruby
429
+ Kward.plugin(id: "com.example.iddqd", version: "1.0.0", api: 1) do |plugin|
430
+ plugin.command "iddqd",
431
+ description: "Run a prompt as system instructions",
432
+ argument_hint: "<prompt>" do |text, ctx|
433
+ if text.strip.empty?
434
+ ctx.say("Usage: /iddqd <prompt>")
435
+ next
436
+ end
437
+
438
+ ctx.request_turn(system: text)
439
+ end
440
+ end
441
+ ```
442
+
443
+ Then enter `/iddqd Answer in French and explain the current design.` The text
444
+ needs no quoting or flag parsing. Kward streams the response just like an ordinary
445
+ turn, with the same tools, permissions, hooks, cancellation, and tab ownership.
446
+ This does not replace Kward's base system prompt or bypass host security policy.
447
+
448
+ The call stages a request and returns `nil`; the host starts the model only after
449
+ the command successfully returns. A handler error or cancellation discards the
450
+ request. Each command may stage one request, containing nonblank text of at most
451
+ 65,536 bytes. Instructions last through tool continuations, prompt refreshes,
452
+ compaction, and retries in that turn, then expire even if the turn fails.
453
+
454
+ Check `ctx.turn_requests_supported?` before offering this behavior on an unknown
455
+ host. It is supported by interactive CLI session commands, asynchronous RPC
456
+ `turns/start` commands, and session-backed transports whose execution profile
457
+ allows plugin commands. Synchronous RPC `commands/run`, plugin actions, plugin
458
+ owned chats, tools, hooks, status renderers, editor/shell prompts, and Pan do not
459
+ provide this capability. Unsupported calls raise an error rather than silently
460
+ launching work or submitting the text as a user prompt. Pan does not dispatch
461
+ plugin slash commands; use the TUI or RPC instead.
462
+
463
+ **History and provider notes:** the invocation and instruction text are stored
464
+ in the session for transcript display and export. Restoring, cloning, or forking
465
+ the session does not reactivate the instructions. Later model requests omit
466
+ these history entries; compaction receives an informational placeholder instead
467
+ of the expired text.
468
+ System-level input uses each provider's native instruction mechanism. On Codex
469
+ (ChatGPT subscription), the command becomes a new `developer` message at its
470
+ position in the conversation: that backend rejects inline `system` messages.
471
+ Direct OpenAI Responses and chat-completions payloads use an ordered `system`
472
+ message. These turn instructions are not folded into the base preamble, so the
473
+ model receives a new instruction after the preceding dialogue.
474
+
475
+ Anthropic and Gemini instead collect system instructions into a separate system
476
+ field; they cannot preserve that ordered-message boundary and require existing
477
+ dialogue. A system-only turn in an empty session is rejected explicitly. Other
478
+ provider/model restrictions surface as normal request errors. No synthetic user
479
+ prompt is inserted.
480
+
481
+ For instructions that should remain active in future turns instead, use prompt
482
+ context below.
483
+
85
484
  ## Add prompt context
86
485
 
87
486
  Prompt context is short text injected into future model requests.
@@ -104,20 +503,53 @@ If plugin state changes and Kward should rebuild the active system message, call
104
503
  ctx.refresh_system_message!
105
504
  ```
106
505
 
107
- ## Add a footer
506
+ ## Add status to the footer
507
+
508
+ Identified plugins can contribute compact status without replacing status from
509
+ other plugins. Give each contribution a stable name:
510
+
511
+ ```ruby
512
+ Kward.plugin(id: "com.example.session-status", version: "1.0.0", api: 1) do |plugin|
513
+ plugin.status "session", order: 10, priority: :high do |ctx|
514
+ {
515
+ text: ctx.session_name || "unnamed",
516
+ tooltip: "Current Kward session"
517
+ }
518
+ end
519
+
520
+ plugin.status "messages", order: 20, priority: :low do |ctx|
521
+ "#{ctx.transcript.messages.length} messages"
522
+ end
523
+ end
524
+ ```
525
+
526
+ Kward joins visible contributions with ` · `. Lower `order` values appear
527
+ first. `priority` may be `:low`, `:normal` (the default), or `:high`. When the
528
+ terminal is too narrow, Kward removes complete low-priority contributions
529
+ first, followed by normal- and high-priority contributions. Among contributions
530
+ with the same priority, later ones are removed first.
531
+
532
+ Return a string for ordinary status, a hash with `text` and optional `tooltip`
533
+ for structured clients, or `nil` to hide the contribution temporarily. One
534
+ renderer failing does not hide status from other plugins. Kward evaluates the
535
+ contributions at most once per second and reuses their values between refreshes.
536
+
537
+ RPC clients receive both the combined `text` fallback and the individual
538
+ structured segments. Terminal footers display the combined text; tooltips are
539
+ available to clients that can render them.
108
540
 
109
- A footer can show compact local status in the terminal UI:
541
+ The older `plugin.footer` API remains supported. Each legacy footer is treated
542
+ as a normal-priority contribution, so footers from different plugins now
543
+ compose instead of replacing one another:
110
544
 
111
545
  ```ruby
112
546
  Kward.plugin do |plugin|
113
547
  plugin.footer do |ctx|
114
- "#{ctx.session_name || 'unnamed'} • #{ctx.transcript.messages.length} messages"
548
+ "#{ctx.session_name || 'unnamed'}"
115
549
  end
116
550
  end
117
551
  ```
118
552
 
119
- Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning. Kward evaluates the active footer at most once per second and reuses its last value between refreshes.
120
-
121
553
  ## Add an interactive command
122
554
 
123
555
  Interactive commands take over the composer region with a Kward-driven render and
@@ -136,7 +568,7 @@ Kward.plugin do |plugin|
136
568
  ui.put(0, x, "X", :red)
137
569
  x = (x + 1) % ui.width
138
570
  key = ui.poll_key
139
- return :exit if key == :ctrl_c || key == "q"
571
+ next :exit if key == "q"
140
572
  ui.render
141
573
  end
142
574
  end
@@ -164,8 +596,9 @@ The `ui` controller object passed to the handler block exposes:
164
596
  | `fps` | Target frame rate |
165
597
 
166
598
  Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
167
- `:backspace`, `:space`, `:pageup`, `:pagedown`) or raw strings for keys
168
- 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`.
169
602
 
170
603
  The tick callback runs at the configured frame rate (1–120 fps, default 30).
171
604
  Calls to `put` and `clear_frame` stage canvas changes; call `render` after the
@@ -179,7 +612,7 @@ Returning `:exit` from the tick callback ends the loop, same as calling
179
612
  cursor, and transcript viewport).
180
613
  - Interactive mode is a distinct state from the busy-input spinner lifecycle —
181
614
  no spinner or busy chrome is shown.
182
- - 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`
183
616
  all exit cleanly and restore the prior composer state.
184
617
  - Resize during interactive mode forces a clean exit and restore.
185
618
 
@@ -190,13 +623,25 @@ in piped/non-interactive mode or through RPC.
190
623
 
191
624
  A plugin can provide a persistent tab with Kward's normal composer, transcript
192
625
  rendering, streaming, image input, cancellation, and tab switching. The plugin
193
- owns its transcript, storage, model behavior, and any global state; it does not
194
- need to use a Kward workspace session.
626
+ owns its transcript and model behavior, while Kward can provide scoped storage,
627
+ configuration, secrets, logging, and resource cleanup. It does not need to use a
628
+ Kward workspace session.
195
629
 
196
630
  ```ruby
197
- Kward.plugin do |plugin|
198
- plugin.tab_type "example", id: "com.example.chat", title: "Example", singleton: :global do |host, descriptor|
199
- ExampleChat.new(client: host.client, descriptor: descriptor)
631
+ Kward.plugin(id: "com.example.plugin", version: "1.0.0", api: 1) do |plugin|
632
+ plugin.tab_type(
633
+ "example",
634
+ id: "com.example.chat",
635
+ title: "Example",
636
+ singleton: :global,
637
+ api: 1,
638
+ capabilities: {
639
+ attachments: [:image],
640
+ steering: false,
641
+ transcript_paging: false
642
+ }
643
+ ) do |host, descriptor|
644
+ ExampleChat.new(client: host.client, storage: host.storage, descriptor: descriptor)
200
645
  end
201
646
  end
202
647
  ```
@@ -210,6 +655,39 @@ Open it from interactive Kward:
210
655
  `id` is a stable persisted identifier: do not change it after release.
211
656
  Use `singleton: :global` for one plugin-managed chat shared by all tab views.
212
657
 
658
+ ### Versioned chat contract
659
+
660
+ Pass `api: 1` and `capabilities:` together to opt into the versioned plugin-chat
661
+ contract. The capability object supports:
662
+
663
+ - `attachments`: currently `[]` or `[:image]`;
664
+ - `steering`: whether the driver supports in-flight steering;
665
+ - `transcript_paging`: whether the driver implements `transcript_page`.
666
+
667
+ Kward validates versioned drivers when they are created. A declared driver must
668
+ implement `messages`, `submit`, `descriptor`, `supports_steering?`, and
669
+ `assistant_label`. Its `supports_steering?` result must match the declaration,
670
+ and a driver declaring transcript paging must implement `transcript_page`.
671
+ Omitting both options preserves the legacy method-probing behavior.
672
+
673
+ The factory's `host` exposes:
674
+
675
+ - `host.plugin_id` (nil for a legacy anonymous plugin) and `host.type_id`;
676
+ - `host.surface`, one of `:local`, `:rpc`, `:transport`, or `:shared` when the
677
+ same runtime can serve RPC and transports;
678
+ - `host.scope_key`, persisted for local tabs and stable for RPC/transport scopes;
679
+ - `host.capabilities`, the declared contract;
680
+ - `host.config`, the identified plugin's immutable private configuration;
681
+ - `host.storage`, isolated by plugin, chat type, and scope;
682
+ - `host.secret(name, env: nil)` and `host.logger`;
683
+ - `host.background` and `host.on_cleanup` for work owned by this chat instance.
684
+
685
+ Closing a local tab or shutting down the shared RPC/transport chat runtime calls
686
+ the driver's optional `close` method (or `shutdown` fallback), then cleans up the
687
+ host's managed resources. Scoped storage remains durable across reconstruction.
688
+ Legacy plugins receive the same host surface using their stable tab type ID as
689
+ the configuration namespace.
690
+
213
691
  Plugin tabs do not notify global transcript observers by default. Set
214
692
  `transcript_events: true` only when the tab explicitly permits its streamed
215
693
  content to be delivered to every installed `on_transcript_event` handler, such
@@ -308,13 +786,15 @@ Handlers receive a `ctx` object. Common methods:
308
786
  - `ctx.workspace_root`
309
787
  - `ctx.args`
310
788
  - `ctx.say(message)`
789
+ - `ctx.result(message:, data:)`
790
+ - `ctx.ui`
311
791
  - `ctx.transcript.messages`
312
792
  - `ctx.session_id`
313
793
  - `ctx.session_name`
314
794
  - `ctx.session_path`
315
795
  - `ctx.refresh_system_message!`
316
796
 
317
- These methods are available in all handler types: commands, footers, prompt context renderers, and transcript event observers. `ctx.say` outputs to the active frontend (terminal or RPC) wherever it is called.
797
+ These methods are available in all handler types, including model-callable tools, although `ctx.result` is the result contract specifically for typed commands and actions. Typed command and action handlers receive their validated hash through `ctx.args`; legacy commands continue to receive text. Model-callable tools and asynchronous TUI/RPC slash commands expose `ctx.cancellation` and `ctx.cancelled?`. `ctx.say` outputs to the active frontend (terminal or RPC) wherever it is called. Interactive `ctx.ui` methods remain capability-gated because not every handler runs in a frontend context that can wait for an answer.
318
798
 
319
799
  The transcript is read-only. Use context methods instead of mutating Kward internals.
320
800
 
@@ -324,15 +804,19 @@ Plugins are available in the CLI and RPC backend.
324
804
 
325
805
  RPC clients can:
326
806
 
807
+ - discover plugin tools through `tools/list`,
808
+ - invoke plugin tools through normal model turns,
327
809
  - list plugin commands through `commands/list`,
328
- - run plugin commands through `commands/run`,
329
- - run plugin slash commands through `turns/start` input such as `/hello World`.
810
+ - run plugin commands through `commands/run`, including typed object arguments and structured results,
811
+ - run plugin slash commands through `turns/start` input such as `/hello World`,
812
+ - discover and run namespaced typed actions through `pluginActions/list` and `pluginActions/run`,
813
+ - render and answer structured plugin UI requests advertised through `extensionUi`.
330
814
 
331
815
  Plugin command output is emitted through normal turn events without calling the model.
332
816
 
333
817
  ## Security
334
818
 
335
- Plugins are local Ruby code. They can read files, write files, run commands, make network requests, and read environment variables as your user.
819
+ Plugins are local Ruby code. They can read files, write files, run commands, make network requests, and read environment variables as your user. Model-callable plugin tools execute in Kward's host process and are not contained by the command sandbox; permission checks decide whether a call starts but do not sandbox trusted plugin code after it begins.
336
820
 
337
821
  Recommended practices:
338
822
 
data/doc/providers.md CHANGED
@@ -117,9 +117,13 @@ Kward combines several sources so a temporary catalog failure does not lock you
117
117
  4. the currently configured model;
118
118
  5. a manual ID entered in `/model`.
119
119
 
120
- When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Empty or incomplete metadata stays visible. Use **Show all models** for embedding, preview, private, or unusually described models.
120
+ When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Unknown or empty metadata and the current selection stay visible. Use **Show all models** for embedding, preview, private, or unusually described models.
121
121
 
122
- Model discovery proves that an ID exists; it does not guarantee account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
122
+ Known model choices can include configured or curated fallbacks, not just discovered IDs. Neither a listing nor successful discovery guarantees account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
123
+
124
+ **Refresh model list** refreshes only the active provider, or the provider chosen in the picker—not every configured provider. OpenRouter uses its own key-associated disk cache; Copilot and Local replace their process-local discovery results. Anthropic consumes its disk catalog alongside curated choices (live discovery requires an API key). API-key providers with discovery use their provider catalogs. Codex and providers without discovery, such as Azure deployment selection, retain curated/configured choices. Failed discovery preserves the last usable catalog.
125
+
126
+ Refreshing is not configuration reload. After another Kward process changes configuration or caches, RPC clients should explicitly call `runtime/reload` then `models/list`. Reload also reloads plugins and reapplies configuration-backed session runtime state; ordinary catalog reads and refreshes do neither. Copilot and Local have no shared persisted model catalog and rediscover lazily after reload. There is no automatic cross-process watcher or model-change notification.
123
127
 
124
128
  ## OAuth availability
125
129
 
@@ -133,8 +137,10 @@ RPC clients should discover providers rather than hard-code this table:
133
137
 
134
138
  - `auth/providers` returns catalog providers and supported authentication methods;
135
139
  - `auth/status` returns sanitized configured/source state;
136
- - `models/list` returns known model entries;
137
- - `models/refresh` refreshes a provider when supported;
140
+ - `models/list` returns the complete known catalog; use `defaultSelectable` for the default picker and the full list for **Show all models**;
141
+ - `models/refresh` returns the catalog plus a safe `refresh` outcome (`provider`, `status`, `fallbackUsed`), distinguishing `success`, `unsupported`, and `failed`;
138
142
  - `models/set` selects the provider and model.
139
143
 
144
+ Check `initialize` model field and refresh metadata capabilities before consuming additive fields. Keep `OpenAI` and `Codex` identities separate and pass provider/model IDs back unchanged, including slashes.
145
+
140
146
  See the [RPC protocol](rpc.md#Config_and_auth_methods) for request shapes and unsupported OAuth capability reporting.