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
@@ -3,7 +3,7 @@ require "set"
3
3
  require_relative "context_budget_meter"
4
4
  require_relative "image_attachments"
5
5
  require_relative "message_access"
6
- require_relative "plugin_registry"
6
+ require_relative "plugins/registry"
7
7
  require_relative "prompts"
8
8
 
9
9
  # Namespace for the Kward CLI agent runtime.
@@ -47,6 +47,8 @@ module Kward
47
47
  attr_accessor :on_compact
48
48
  # @return [Proc, nil] callback invoked when a tool execution record should be persisted
49
49
  attr_accessor :on_tool_execution
50
+ # @return [Proc, nil] callback for branch-anchored turn summary metadata
51
+ attr_accessor :on_turn_summary
50
52
  # @return [Proc, nil] callback invoked when runtime metadata should be persisted
51
53
  attr_accessor :on_runtime_update
52
54
  # @return [Proc, nil] callback invoked when the system prompt runtime state changes
@@ -123,6 +125,14 @@ module Kward
123
125
  append_message(message)
124
126
  end
125
127
 
128
+ def finish_turn(summary)
129
+ message = @messages.last
130
+ return unless message
131
+
132
+ message["turn_summary"] = summary
133
+ @on_turn_summary&.call(message, summary)
134
+ end
135
+
126
136
  def append_tool(tool_call_id:, name:, content:)
127
137
  append_message({
128
138
  role: "tool",
@@ -176,9 +186,38 @@ module Kward
176
186
  "toolout_#{digest}"
177
187
  end
178
188
 
189
+ # Scopes plugin instructions to one host-owned turn, including retries.
190
+ # The overlay is deliberately not persisted or folded into the base prompt.
191
+ def with_system_turn(request)
192
+ previous = @system_turn
193
+ raise ArgumentError, "A system-instruction turn is already active" if previous
194
+
195
+ @system_turn = request
196
+ yield
197
+ ensure
198
+ @system_turn = previous
199
+ end
200
+
201
+ def append_system_turn(request)
202
+ append_message(request.history_message)
203
+ end
204
+
179
205
  # @return [Array<Hash>] provider request context: current system prompt plus durable transcript
180
206
  def context_messages
181
- @system_message ? [@system_message] + @messages : @messages.dup
207
+ instruction = { role: "system", content: @system_turn.system, system_turn: true } if @system_turn
208
+ inserted = false
209
+ messages = @messages.filter_map do |message|
210
+ record = message[:plugin_system_turn] || message["plugin_system_turn"]
211
+ next message.reject { |key, _| key.to_s == "turn_summary" } unless record
212
+ next unless @system_turn && (record[:id] || record["id"]) == @system_turn.id
213
+
214
+ inserted = true
215
+ instruction
216
+ end
217
+ # Compaction can remove the history marker; reissue the current directive
218
+ # after the compacted context rather than demoting it to the base prompt.
219
+ messages << instruction if instruction && !inserted
220
+ @system_message ? [@system_message] + messages : messages
182
221
  end
183
222
 
184
223
  # Rebuilds the system message from current config, memory, plugins, and
@@ -0,0 +1,14 @@
1
+ module Kward
2
+ # Select shell mode before loading the coding agent or parsing its options.
3
+ module Entrypoint
4
+ def self.run(arguments = ARGV, name: $PROGRAM_NAME)
5
+ if arguments.first == "shell"
6
+ require_relative "shell/native_process"
7
+ NativeShell::NativeProcess.standalone(arguments.drop(1), name: "#{name} shell", program: "kward shell", edit_lines: true, load_rc: true, shell_agent: true)
8
+ else
9
+ require_relative "../kward"
10
+ CLI.new(argv: arguments).run
11
+ end
12
+ end
13
+ end
14
+ end
data/lib/kward/events.rb CHANGED
@@ -11,7 +11,9 @@ module Kward
11
11
  SteeringApplied = Struct.new(:count, keyword_init: true)
12
12
  ToolCall = Struct.new(:tool_call, keyword_init: true)
13
13
  ToolUpdate = Struct.new(:tool_call, :content, :elapsed_ms, keyword_init: true)
14
+ ImageReady = Struct.new(:tool_call, :image, keyword_init: true)
14
15
  ToolResult = Struct.new(:tool_call, :content, keyword_init: true)
15
16
  Answer = Struct.new(:content, keyword_init: true)
17
+ TurnSummary = Struct.new(:summary, keyword_init: true)
16
18
  end
17
19
  end
@@ -0,0 +1,237 @@
1
+ require "fileutils"
2
+ require "securerandom"
3
+ require "tmpdir"
4
+ require_relative "model/codex_images"
5
+ require_relative "shell/native_directory"
6
+
7
+ module Kward
8
+ # Owns unsaved preview bytes. Only the frontend can export or discard them.
9
+ class GeneratedImages
10
+ Error = Class.new(StandardError)
11
+ Preview = Struct.new(:id, :filename, :root, :size, keyword_init: true)
12
+ Entry = Struct.new(:owner, :preview, :path, keyword_init: true)
13
+ MAX_PREVIEWS = 16
14
+ FETCH_CHUNK_BYTES = 256 * 1024
15
+ LOCK_FLAGS = File::RDWR | File::CREAT | File::NOFOLLOW
16
+
17
+ def initialize(base: File.join(Dir.tmpdir, "kward-images-#{Process.uid}"))
18
+ @base = base
19
+ @entries = {}
20
+ @mutex = Mutex.new
21
+ reap_crashed_runs
22
+ end
23
+
24
+ def add(owner, bytes, cancellation: nil)
25
+ raise Error, "Invalid or oversized PNG." unless CodexImages.valid_png?(bytes)
26
+
27
+ @mutex.synchronize do
28
+ cancellation&.raise_if_cancelled!
29
+ raise Error, "Image preview storage is closed." if @closed
30
+ raise Error, "Too many pending images; discard a preview before generating another." if @entries.size >= MAX_PREVIEWS
31
+
32
+ initialize_run unless @run
33
+ id = SecureRandom.hex(16)
34
+ preview = Preview.new(id: id, filename: "kward-image-#{id[0, 8]}.png", root: File.realpath(owner.workspace_root), size: bytes.bytesize).freeze
35
+ path = File.join(@run, "#{id}.png")
36
+ begin
37
+ File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.binmode.write(bytes) }
38
+ cancellation&.raise_if_cancelled!
39
+ @entries[id] = Entry.new(owner: owner, preview: preview, path: path)
40
+ ensure
41
+ FileUtils.rm_f(path) unless @entries.key?(id)
42
+ end
43
+ preview
44
+ end
45
+ rescue SystemCallError
46
+ raise Error, "Could not store the generated image preview."
47
+ end
48
+
49
+ def path(owner, id)
50
+ @mutex.synchronize { entry_for(owner, id).path }
51
+ end
52
+
53
+ def fetch(owner, id, offset: 0)
54
+ raise Error, "Invalid image offset." unless offset.is_a?(Integer) && offset >= 0
55
+
56
+ @mutex.synchronize do
57
+ entry = entry_for(owner, id)
58
+ raise Error, "Invalid image offset." if offset > entry.preview.size
59
+ return [entry.preview, "".b] if offset == entry.preview.size
60
+
61
+ bytes = File.binread(entry.path, FETCH_CHUNK_BYTES, offset)
62
+ raise Error, "Image preview is unavailable or has been discarded." unless bytes
63
+
64
+ [entry.preview, bytes]
65
+ end
66
+ rescue SystemCallError
67
+ raise Error, "Image preview is unavailable or has been discarded."
68
+ end
69
+
70
+ def save_to_project(owner, id, directory = ".")
71
+ export(owner, id, directory, project: true)
72
+ end
73
+
74
+ def save_to_downloads(owner, id)
75
+ export(owner, id, downloads_directory)
76
+ rescue SystemCallError
77
+ raise Error, "Could not locate the Downloads folder."
78
+ end
79
+
80
+ def discard(owner, id)
81
+ @mutex.synchronize do
82
+ entry = entry_for(owner, id)
83
+ FileUtils.rm_f(entry.path)
84
+ @entries.delete(id)
85
+ end
86
+ true
87
+ end
88
+
89
+ def discard_owner(owner)
90
+ @mutex.synchronize do
91
+ @entries.delete_if do |_id, entry|
92
+ next false unless entry.owner.equal?(owner)
93
+
94
+ FileUtils.rm_f(entry.path)
95
+ true
96
+ end
97
+ end
98
+ end
99
+
100
+ def close
101
+ @mutex.synchronize do
102
+ @closed = true
103
+ @entries.clear
104
+ with_base_lock { FileUtils.remove_entry_secure(@run) } if @run && File.directory?(@run)
105
+ ensure
106
+ @run = nil
107
+ @run_lock&.close
108
+ @run_lock = nil
109
+ end
110
+ rescue Error, SystemCallError
111
+ # A later instance will reap the run if removal could not finish.
112
+ nil
113
+ end
114
+
115
+ private
116
+
117
+ def initialize_run
118
+ begin
119
+ Dir.mkdir(@base, 0o700)
120
+ rescue Errno::EEXIST
121
+ nil
122
+ end
123
+ with_base_lock do
124
+ run = Dir.mktmpdir("run-", @base)
125
+ run_lock = File.open(File.join(run, "lock"), LOCK_FLAGS, 0o600)
126
+ run_lock.flock(File::LOCK_EX)
127
+ @run, @run_lock = run, run_lock
128
+ end
129
+ end
130
+
131
+ def reap_crashed_runs
132
+ with_base_lock { remove_stale_runs }
133
+ rescue Error, SystemCallError
134
+ # The directory may not exist yet. Report storage errors on generation.
135
+ nil
136
+ end
137
+
138
+ def with_base_lock
139
+ stat = File.lstat(@base)
140
+ raise Error, "Image preview directory is not private." unless stat.directory? && stat.uid == Process.uid && (stat.mode & 0o077).zero?
141
+
142
+ File.open(File.join(@base, "lock"), LOCK_FLAGS, 0o600) do |lock|
143
+ lock.flock(File::LOCK_EX)
144
+ yield
145
+ end
146
+ end
147
+
148
+ def remove_stale_runs
149
+ Dir.each_child(@base) do |name|
150
+ next unless name.start_with?("run-")
151
+
152
+ path = File.join(@base, name)
153
+ next unless File.lstat(path).directory?
154
+
155
+ File.open(File.join(path, "lock"), LOCK_FLAGS, 0o600) do |lock|
156
+ FileUtils.remove_entry_secure(path) if lock.flock(File::LOCK_EX | File::LOCK_NB)
157
+ end
158
+ rescue SystemCallError
159
+ next
160
+ end
161
+ end
162
+
163
+ def entry_for(owner, id)
164
+ entry = @entries[id]
165
+ raise Error, "Image preview is unavailable or has been discarded." unless entry&.owner&.equal?(owner)
166
+
167
+ entry
168
+ end
169
+
170
+ def export(owner, id, directory, project: false)
171
+ @mutex.synchronize do
172
+ entry = entry_for(owner, id)
173
+ root = entry.preview.root if project
174
+ destination = File.expand_path(directory.to_s, root)
175
+ handle = NativeShell::Directory.new(destination)
176
+ begin
177
+ resolved = handle.physical_path
178
+ if root && !within?(resolved, root)
179
+ raise Error, "Choose a directory inside the project."
180
+ end
181
+
182
+ write_exclusively(handle, resolved, entry)
183
+ ensure
184
+ handle.close
185
+ end
186
+ end
187
+ rescue IOError, SystemCallError, ArgumentError
188
+ raise Error, "Could not save the image. Choose an existing, writable directory."
189
+ end
190
+
191
+ def within?(path, root)
192
+ path == root || path.start_with?(root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}")
193
+ end
194
+
195
+ def write_exclusively(handle, directory, entry)
196
+ stem = File.basename(entry.preview.filename, ".png")
197
+ 1000.times do |index|
198
+ name = index.zero? ? "#{stem}.png" : "#{stem}-#{index + 1}.png"
199
+ path = File.join(directory, name)
200
+ flags = File::WRONLY | File::CREAT | File::EXCL
201
+ output = handle.open_file(name, flags)
202
+ begin
203
+ stat = output.stat
204
+ output.binmode
205
+ IO.copy_stream(entry.path, output)
206
+ output.close
207
+ rescue IOError, SystemCallError
208
+ remove_failed_export(path, stat) if stat
209
+ raise
210
+ ensure
211
+ output.close unless output.closed?
212
+ end
213
+ return path
214
+ rescue Errno::EEXIST
215
+ next
216
+ end
217
+ raise Error, "Could not find an unused image filename."
218
+ end
219
+
220
+ def remove_failed_export(path, stat)
221
+ current = File.lstat(path)
222
+ File.unlink(path) if stat.ino == current.ino && stat.dev == current.dev
223
+ rescue SystemCallError
224
+ nil
225
+ end
226
+
227
+ def downloads_directory
228
+ home = Dir.home
229
+ config = File.join(ENV.fetch("XDG_CONFIG_HOME", File.join(home, ".config")), "user-dirs.dirs")
230
+ if RUBY_PLATFORM.include?("linux") && File.file?(config)
231
+ value = File.read(config, 16_384)[/^XDG_DOWNLOAD_DIR="(\$HOME(?:\/[^"\n]*)?|\/[^"\n]*)"$/, 1]
232
+ return value.sub(/\A\$HOME(?=\/|\z)/) { home } if value
233
+ end
234
+ File.join(home, "Downloads")
235
+ end
236
+ end
237
+ end
@@ -4,7 +4,7 @@ require "open3"
4
4
  require "shellwords"
5
5
  require "tmpdir"
6
6
  require "uri"
7
- require_relative "terminal_image_support"
7
+ require_relative "terminal/image_support"
8
8
 
9
9
  # Namespace for the Kward CLI agent runtime.
10
10
  module Kward
@@ -80,8 +80,10 @@ module Kward
80
80
 
81
81
  def normalize(body)
82
82
  payload = JSON.parse(body.to_s)
83
- entries = payload["data"] || payload["models"] || []
84
- Array(entries).filter_map { |entry| normalize_entry(entry) }.sort_by { |entry| entry["id"] }
83
+ entries = payload.is_a?(Hash) && (payload["data"] || payload["models"])
84
+ raise "Invalid model catalog" unless entries.is_a?(Array)
85
+
86
+ entries.filter_map { |entry| normalize_entry(entry) }.sort_by { |entry| entry["id"] }
85
87
  rescue JSON::ParserError
86
88
  raise "#{@provider.name} model refresh returned invalid JSON"
87
89
  end
@@ -89,7 +91,8 @@ module Kward
89
91
  def normalize_entry(entry)
90
92
  return unless entry.is_a?(Hash)
91
93
 
92
- id = (entry["id"] || entry["name"]).to_s.delete_prefix("models/")
94
+ id = (entry["id"] || entry["name"]).to_s
95
+ id = id.delete_prefix("models/") if @provider.id == "gemini"
93
96
  return if id.empty?
94
97
 
95
98
  {
@@ -8,13 +8,14 @@ require_relative "../auth/openai_oauth"
8
8
  require_relative "../cancellation"
9
9
  require_relative "../config_files"
10
10
  require_relative "../http"
11
- require_relative "../openrouter_model_cache"
11
+ require_relative "openrouter_model_cache"
12
12
  require_relative "context_overflow"
13
13
  require_relative "azure_openai_config"
14
14
  require_relative "copilot_models"
15
15
  require_relative "model_info"
16
16
  require_relative "sources"
17
17
  require_relative "payloads"
18
+ require_relative "codex_images"
18
19
  require_relative "../telemetry/logger"
19
20
  require_relative "stream_parser"
20
21
 
@@ -110,7 +111,7 @@ module Kward
110
111
  @local_models = nil
111
112
  end
112
113
 
113
- def chat(messages, tools: [], on_reasoning_delta: nil, on_reasoning_boundary: nil, on_assistant_delta: nil, on_retry: nil, cancellation: nil, steering: nil, max_tokens: nil, provider: nil, model: nil, reasoning: nil, provider_required: false)
114
+ def chat(messages, tools: [], on_reasoning_delta: nil, on_reasoning_boundary: nil, on_assistant_delta: nil, on_retry: nil, cancellation: nil, steering: nil, max_tokens: nil, provider: nil, model: nil, reasoning: nil, provider_required: false, text_format: nil)
114
115
  cancellation&.raise_if_cancelled!
115
116
  requested_provider = provider
116
117
  validate_required_provider!(requested_provider) if provider_required
@@ -126,7 +127,8 @@ module Kward
126
127
  current_model = resolved_copilot_chat_model(current_model) if resolved_provider == "Copilot" && model.nil?
127
128
 
128
129
  validate_image_support!(resolved_provider, current_model, messages)
129
- request_body = JSON.dump(request_body_payload(resolved_provider, messages, tools, max_tokens: max_tokens, model: current_model, reasoning: reasoning))
130
+ tools = tools.reject { |tool| ToolCall.name(tool) == "generate_image" } if resolved_provider != "Codex"
131
+ request_body = JSON.dump(request_body_payload(resolved_provider, messages, tools, max_tokens: max_tokens, model: current_model, reasoning: reasoning, text_format: text_format))
130
132
  with_retries(resolved_provider, current_model, request_bytes: request_body.bytesize, on_retry: on_retry, cancellation: cancellation) do
131
133
  request_started_at = @telemetry_logger.monotonic_now
132
134
  message = nil
@@ -166,6 +168,16 @@ module Kward
166
168
  raise e
167
169
  end
168
170
 
171
+ # Generates via the Codex subscription only, never using a public API key.
172
+ def generate_codex_image(prompt, turn_id: nil, cancellation: nil)
173
+ _url, token, provider, account_id = credentials(provider: "Codex")
174
+ unless provider == "Codex" && !token.to_s.empty?
175
+ raise CodexImages::Error, "Sign in to Codex to generate images."
176
+ end
177
+
178
+ CodexImages.generate(prompt, token: token, account_id: account_id, turn_id: turn_id, cancellation: cancellation)
179
+ end
180
+
169
181
  # Returns the active provider label after applying env/config/credential fallback rules.
170
182
  def current_provider
171
183
  _url, _token, provider = credentials
@@ -226,11 +238,12 @@ module Kward
226
238
  metadata = openrouter_cached_model_entries.find { |entry| (entry["id"] || entry[:id]).to_s == id }
227
239
  model_entry("OpenRouter", id, current: provider == "OpenRouter" && openrouter_model == id, metadata: metadata)
228
240
  end
241
+ models << model_entry("OpenRouter", openrouter_model, current: provider == "OpenRouter") unless openrouter_model.to_s.empty? || openrouter_choices.include?(openrouter_model)
229
242
  end
230
243
 
231
244
  if provider_logged_in?("Copilot")
232
245
  copilot_model = model_for("Copilot")
233
- copilot_choices = provider == "Copilot" ? copilot_model_choices : static_copilot_model_choices
246
+ copilot_choices = provider == "Copilot" || @copilot_models ? copilot_model_choices : static_copilot_model_choices
234
247
  models += copilot_choices.map do |id|
235
248
  model_entry("Copilot", id, current: provider == "Copilot" && copilot_model == id)
236
249
  end
@@ -239,10 +252,13 @@ module Kward
239
252
 
240
253
  if provider_logged_in?("Anthropic")
241
254
  anthropic_model = model_for("Anthropic")
242
- models += ModelInfo::ANTHROPIC_MODEL_CHOICES.map do |id|
243
- model_entry("Anthropic", id, current: provider == "Anthropic" && anthropic_model == id)
255
+ anthropic_entries = ModelSources.new(provider_id: "anthropic", api_key: @api_key_store.fetch("anthropic")).models
256
+ anthropic_choices = (anthropic_entries.map { |entry| entry.fetch("id") } + ModelInfo::ANTHROPIC_MODEL_CHOICES).uniq
257
+ models += anthropic_choices.map do |id|
258
+ metadata = anthropic_entries.find { |entry| entry.fetch("id") == id }
259
+ model_entry("Anthropic", id, current: provider == "Anthropic" && anthropic_model == id, metadata: metadata)
244
260
  end
245
- models << model_entry("Anthropic", anthropic_model, current: provider == "Anthropic") unless ModelInfo::ANTHROPIC_MODEL_CHOICES.include?(anthropic_model)
261
+ models << model_entry("Anthropic", anthropic_model, current: provider == "Anthropic") unless anthropic_choices.include?(anthropic_model)
246
262
  end
247
263
 
248
264
  ProviderCatalog.api_key_providers.each do |catalog_provider|
@@ -270,15 +286,43 @@ module Kward
270
286
  models.sort_by { |model| [model[:provider], model[:id]] }
271
287
  end
272
288
 
273
- # Refreshes cached choices for an API-key provider.
289
+ # Retains the array return value used by terminal pickers and internal callers.
274
290
  def refresh_available_models(provider: nil)
291
+ refresh_model_catalog(provider: provider)
292
+ available_models
293
+ end
294
+
295
+ # Refreshes only one provider and reports a safe, frontend-neutral outcome.
296
+ # Failed discovery never replaces the last usable catalog or returns raw errors.
297
+ def refresh_model_catalog(provider: nil)
275
298
  provider ||= current_provider
299
+ provider = "OpenAI" if provider.to_s == "openai_api"
276
300
  catalog_provider = ProviderCatalog.find_by_name(provider) || ProviderCatalog.find(provider.to_s.downcase)
277
- return available_models unless catalog_provider&.api_key?
278
- return available_models unless ProviderCatalog.runtime(catalog_provider.id).automatic_model_discovery?
301
+ provider = ModelInfo.provider_label(catalog_provider&.id == "openai" ? "OpenAI" : catalog_provider&.id || provider)
302
+ status = "success"
279
303
 
280
- ModelSources.new(provider_id: catalog_provider.id, api_key: @api_key_store.fetch(catalog_provider.id)).refresh
281
- available_models
304
+ case provider
305
+ when "OpenRouter"
306
+ @openrouter_models = openrouter_model_cache.refresh.fetch("models")
307
+ when "Copilot"
308
+ fetch_copilot_models(refresh: true)
309
+ when "Local"
310
+ local_model_choices(refresh: true)
311
+ else
312
+ if catalog_provider&.api_key? && ProviderCatalog.runtime(catalog_provider.id).automatic_model_discovery?
313
+ ModelSources.new(provider_id: catalog_provider.id, api_key: @api_key_store.fetch(catalog_provider.id)).refresh(strict: true)
314
+ else
315
+ status = "unsupported"
316
+ end
317
+ end
318
+
319
+ { provider: provider, status: status, fallbackUsed: status != "success" }
320
+ rescue StandardError
321
+ # Avoid an implicit retry during the following list read when no prior
322
+ # in-memory catalog exists. Configured/curated choices remain available.
323
+ @copilot_models ||= [] if provider == "Copilot"
324
+ @local_models ||= [] if provider == "Local"
325
+ { provider: provider, status: "failed", fallbackUsed: true }
282
326
  end
283
327
 
284
328
  # Projects messages/tools into the provider-specific context shape without sending it.
@@ -691,7 +735,7 @@ module Kward
691
735
  end
692
736
  end
693
737
 
694
- def request_body_payload(provider, messages, tools, max_tokens: nil, model: nil, reasoning: nil)
738
+ def request_body_payload(provider, messages, tools, max_tokens: nil, model: nil, reasoning: nil, text_format: nil)
695
739
  reasoning = false unless ModelInfo.reasoning_supported?(provider, model)
696
740
 
697
741
  if provider == "Azure OpenAI"
@@ -699,9 +743,9 @@ module Kward
699
743
  elsif provider == "Google Gemini"
700
744
  gemini_payload(messages, tools, max_tokens: max_tokens, model: model)
701
745
  elsif provider == "OpenAI"
702
- openai_responses_payload(messages, tools, max_tokens: max_tokens, model: model, reasoning: reasoning)
746
+ openai_responses_payload(messages, tools, max_tokens: max_tokens, model: model, reasoning: reasoning, text_format: text_format)
703
747
  elsif provider == "Codex"
704
- codex_payload(messages, tools, max_tokens: max_tokens, model: model, reasoning: reasoning)
748
+ codex_payload(messages, tools, max_tokens: max_tokens, model: model, reasoning: reasoning, text_format: text_format)
705
749
  elsif provider == "Anthropic"
706
750
  anthropic_payload(messages, tools, max_tokens: max_tokens, model: model, reasoning: reasoning)
707
751
  elsif provider == "Copilot" && copilot_responses_model?(model)
@@ -712,7 +756,7 @@ module Kward
712
756
  end
713
757
 
714
758
  def copilot_responses_model?(model)
715
- model.to_s.match?(/\Agpt-5(?:\.|-|\z)/)
759
+ model.to_s.match?(/\Agpt-(?:5|6)(?:\.|-|\z)/)
716
760
  end
717
761
 
718
762
  def model_entry(provider, id, current: false, metadata: nil)
@@ -733,23 +777,27 @@ module Kward
733
777
  ModelInfo.context_window(provider, id, openrouter_models: openrouter_cached_model_entries)
734
778
  end
735
779
 
736
- def local_model_choices
737
- return @local_models if @local_models
780
+ def local_model_choices(refresh: false)
781
+ return @local_models if @local_models && !refresh
738
782
 
739
783
  url = local_models_url
740
784
  request = Http.apply_user_agent(Net::HTTP::Get.new(url))
741
785
  request["Authorization"] = "Bearer #{local_api_key}" unless local_api_key.to_s.empty?
742
786
  request["Accept"] = "application/json"
743
787
  response = Net::HTTP.start(url.hostname, url.port, use_ssl: url.scheme == "https", read_timeout: stream_idle_timeout_seconds) { |http| http.request(request) }
744
- return @local_models = [] unless response.is_a?(Net::HTTPSuccess)
788
+ raise "Local model discovery failed" unless response.is_a?(Net::HTTPSuccess)
745
789
 
746
790
  body = JSON.parse(response.body)
747
- entries = body["data"] || body["models"] || []
748
- @local_models = Array(entries).filter_map do |entry|
791
+ entries = body.is_a?(Hash) && (body["data"] || body["models"])
792
+ raise "Invalid Local model catalog" unless entries.is_a?(Array)
793
+
794
+ @local_models = entries.filter_map do |entry|
749
795
  entry.is_a?(Hash) ? entry["id"] || entry[:id] || entry["model"] || entry[:model] : entry
750
796
  end.map(&:to_s).map(&:strip).reject(&:empty?).uniq
751
797
  rescue StandardError
752
- @local_models = []
798
+ raise if refresh
799
+
800
+ @local_models ||= []
753
801
  end
754
802
 
755
803
  def openrouter_model_choices
@@ -787,11 +835,11 @@ module Kward
787
835
  CopilotModels.resolved_chat_model(configured_model, fetch_copilot_models)
788
836
  end
789
837
 
790
- def fetch_copilot_models
791
- return @copilot_models if @copilot_models
838
+ def fetch_copilot_models(refresh: false)
839
+ return @copilot_models if @copilot_models && !refresh
792
840
 
793
841
  token = github_access_token.to_s
794
- return [] if token.empty?
842
+ raise "No Copilot token found" if token.empty?
795
843
 
796
844
  url = URI("#{@github_oauth.base_url}/models")
797
845
  request = Http.apply_user_agent(Net::HTTP::Get.new(url))
@@ -800,10 +848,12 @@ module Kward
800
848
  copilot_headers([]).each { |key, value| request[key] = value }
801
849
 
802
850
  response = Net::HTTP.start(url.hostname, url.port, use_ssl: true) { |http| http.request(request) }
803
- return [] unless response.is_a?(Net::HTTPSuccess)
851
+ raise "Copilot model discovery failed" unless response.is_a?(Net::HTTPSuccess)
804
852
 
805
- @copilot_models = CopilotModels.parse(response.body)
853
+ @copilot_models = CopilotModels.parse(response.body, strict: refresh)
806
854
  rescue StandardError
855
+ raise if refresh
856
+
807
857
  []
808
858
  end
809
859
 
@@ -972,24 +1022,38 @@ module Kward
972
1022
 
973
1023
  input_tokens = integer_value(usage, "input_tokens", "prompt_tokens")
974
1024
  output_tokens = integer_value(usage, "output_tokens", "completion_tokens")
975
- cache_read_tokens = positive_integer(
1025
+ cache_read_tokens = token_count(
976
1026
  nested_value(usage, "input_tokens_details", "cached_tokens") ||
977
1027
  nested_value(usage, "prompt_tokens_details", "cached_tokens") ||
978
1028
  usage["cache_read_tokens"] || usage[:cache_read_tokens] || usage["cacheReadTokens"] || usage[:cacheReadTokens] || usage["cache_read_input_tokens"] || usage[:cache_read_input_tokens]
979
1029
  )
980
- cache_write_tokens = integer_value(usage, "cache_write_tokens", "cacheWriteTokens", "cache_creation_input_tokens")
1030
+ cache_write_tokens = token_count(
1031
+ nested_value(usage, "input_tokens_details", "cache_write_tokens") ||
1032
+ integer_value(usage, "cache_write_tokens", "cacheWriteTokens", "cache_creation_input_tokens")
1033
+ )
1034
+ reasoning_tokens = token_count(
1035
+ nested_value(usage, "output_tokens_details", "reasoning_tokens") ||
1036
+ nested_value(usage, "completion_tokens_details", "reasoning_tokens") ||
1037
+ integer_value(usage, "reasoning_tokens")
1038
+ )
1039
+ # Anthropic reports uncached input separately; OpenAI/Gemini include cache
1040
+ # tokens in input. Normalize to inclusive input before computing totals.
1041
+ if input_tokens && %w[cache_read_input_tokens cache_creation_input_tokens].any? { |key| usage.key?(key) || usage.key?(key.to_sym) }
1042
+ input_tokens += cache_read_tokens.to_i + cache_write_tokens.to_i
1043
+ end
981
1044
  total_tokens = integer_value(usage, "total_tokens", "totalTokens")
982
- total_tokens ||= [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens].compact.sum
983
- return nil unless total_tokens&.positive? || input_tokens&.positive? || output_tokens&.positive?
1045
+ total_tokens ||= input_tokens.to_i + output_tokens.to_i if input_tokens || output_tokens
1046
+ return nil if total_tokens.nil?
984
1047
 
985
1048
  {
986
- "input_tokens" => input_tokens || 0,
987
- "output_tokens" => output_tokens || 0,
988
- "cache_read_tokens" => cache_read_tokens || 0,
989
- "cache_write_tokens" => cache_write_tokens || 0,
990
- "total_tokens" => total_tokens || 0,
1049
+ "input_tokens" => input_tokens,
1050
+ "output_tokens" => output_tokens,
1051
+ "cache_read_tokens" => cache_read_tokens,
1052
+ "cache_write_tokens" => cache_write_tokens,
1053
+ "reasoning_tokens" => reasoning_tokens,
1054
+ "total_tokens" => total_tokens,
991
1055
  "estimated" => false
992
- }
1056
+ }.compact
993
1057
  end
994
1058
 
995
1059
  def integer_value(source, *keys)
@@ -998,7 +1062,7 @@ module Kward
998
1062
  key = keys.find { |candidate| source.key?(candidate) || source.key?(candidate.to_sym) }
999
1063
  return nil unless key
1000
1064
 
1001
- positive_integer(source[key] || source[key.to_sym])
1065
+ token_count(source[key] || source[key.to_sym])
1002
1066
  end
1003
1067
 
1004
1068
  def nested_value(source, outer_key, inner_key)
@@ -1008,6 +1072,11 @@ module Kward
1008
1072
  outer[inner_key] || outer[inner_key.to_sym]
1009
1073
  end
1010
1074
 
1075
+ def token_count(value)
1076
+ integer = Integer(value, exception: false)
1077
+ integer if integer && integer >= 0
1078
+ end
1079
+
1011
1080
  def positive_integer(value)
1012
1081
  integer = value.to_i
1013
1082
  integer.positive? ? integer : nil