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
@@ -1,11 +1,24 @@
1
- require "base64"
2
-
3
1
  # Namespace for the Kward CLI agent runtime.
4
2
  module Kward
5
3
  # Terminal control escape sequence builders.
6
4
  module TerminalSequences
5
+ ALERT = "\a".freeze
6
+ CARRIAGE_RETURN = "\r".freeze
7
+ ERASE_LINE_END = "\e[K".freeze
8
+ CLEAR_VISIBLE_SCREEN = "\e[2J\e[H".freeze
9
+ ALTERNATE_SCREEN_ENTER = "\e[?1049h".freeze
10
+ ALTERNATE_SCREEN_LEAVE = "\e[?1049l".freeze
7
11
  KEYBOARD_PROTOCOL_ENABLE = "\e[>25u".freeze
8
12
  KEYBOARD_PROTOCOL_RESTORE = "\e[<u".freeze
13
+ KEYBOARD_PROTOCOL_SET = "\e[=25u".freeze
14
+ # Cancel incomplete controls before restoring the composer's terminal baseline.
15
+ CONTROL_SEQUENCE_CANCEL = "\x18\e\\".freeze
16
+ COMPOSER_MODES_RESTORE = (
17
+ "\e[?2026l\e[?1049l\e[?1047l\e[?47l" +
18
+ "\e[?1l\e>\e[?1004l\e[>4;0m" +
19
+ "\e[?1000l\e[?1002l\e[?1003l\e[?1005l\e[?1006l\e[?1015l" +
20
+ "\e[?6l\e[?7h\e[4l"
21
+ ).freeze
9
22
  BRACKETED_PASTE_ENABLE = "\e[?2004h".freeze
10
23
  BRACKETED_PASTE_RESTORE = "\e[?2004l".freeze
11
24
  BRACKETED_PASTE_START = "\e[200~".freeze
@@ -22,8 +35,28 @@ module Kward
22
35
  SGR_INVERSE = "\e[7m".freeze
23
36
  SGR_INVERSE_OFF = "\e[27m".freeze
24
37
 
38
+ KITTY_GRAPHICS_PREFIX = "\e_G".freeze
39
+ KITTY_GRAPHICS_COMMAND = /\A\e_G(?:[A-Za-z]=[A-Za-z0-9+-]+(?:,[A-Za-z]=[A-Za-z0-9+-]+)*)?(?:;[A-Za-z0-9+\/=]*)?\e\\\z/.freeze
40
+ DEVICE_QUERY = /\A\e\[(?:>?0?c|>0?q|\?u|[56]n|\?6n|1[468]t)\z/.freeze
41
+
25
42
  module_function
26
43
 
44
+ def keyboard_mode_mutation?(sequence)
45
+ sequence.match?(/\A\e\[[><=][0-9;]*u\z/) ||
46
+ sequence.match?(/\A\e\[>4(?:;[0-9]*)?m\z/)
47
+ end
48
+
49
+ def keyboard_mode_reset?(sequence)
50
+ return true if sequence == "\ec" || sequence == "\e[!p"
51
+
52
+ match = sequence.match(/\A\e\[\?([0-9;]+)[hl]\z/)
53
+ match && (match[1].split(";") & %w[47 1047 1049]).any?
54
+ end
55
+
56
+ def sgr(*codes)
57
+ "\e[#{codes.join(';')}m"
58
+ end
59
+
27
60
  def scroll_region(top, bottom)
28
61
  "\e[#{top};#{bottom}r"
29
62
  end
@@ -36,12 +69,20 @@ module Kward
36
69
  "\e[#{row};#{col}H"
37
70
  end
38
71
 
72
+ def move_up(rows)
73
+ "\e[#{rows}A"
74
+ end
75
+
76
+ def move_down(rows)
77
+ "\e[#{rows}B"
78
+ end
79
+
39
80
  def move_to_column(column)
40
81
  "\e[#{column}G"
41
82
  end
42
83
 
43
84
  def osc52(text)
44
- "\e]52;c;#{Base64.strict_encode64(text.to_s)}\a"
85
+ "\e]52;c;#{[text.to_s].pack("m0")}\a"
45
86
  end
46
87
 
47
88
  def kitty_graphics(data, image_id:, columns: nil, rows: nil, move_cursor: true)
@@ -78,7 +119,7 @@ module Kward
78
119
  params = ["inline=1", "preserveAspectRatio=1"]
79
120
  params << "width=#{width}" if width
80
121
  params << "height=#{height}" if height
81
- params << "name=#{Base64.strict_encode64(File.basename(name))}" if name
122
+ params << "name=#{[File.basename(name)].pack("m0")}" if name
82
123
  "\e]1337;File=#{params.join(";")}:#{data}\a"
83
124
  end
84
125
  end
@@ -1,3 +1,5 @@
1
+ require_relative "workspace_targets"
2
+
1
3
  # Namespace for the Kward CLI agent runtime.
2
4
  module Kward
3
5
  # Model-callable tool wrappers and their argument schemas.
@@ -54,6 +56,22 @@ module Kward
54
56
  end
55
57
  end
56
58
 
59
+ # Configures the active workspace and any additional host-scoped targets.
60
+ def configure_workspace_targets(workspace, workspace_targets)
61
+ @workspace = workspace
62
+ @workspace_targets = workspace_targets || WorkspaceTargets.new(active: workspace)
63
+ end
64
+
65
+ # Adds the optional target selector when additional workspaces are available.
66
+ def targeted_properties(properties)
67
+ @workspace_targets.properties(properties)
68
+ end
69
+
70
+ # Resolves the requested role through the trusted target map.
71
+ def workspace_for(args)
72
+ @workspace_targets.workspace_for(args)
73
+ end
74
+
57
75
  # Reads a tool argument while accepting symbol or string keys from restored calls.
58
76
  def argument(args, key, default = nil)
59
77
  return args[key] if args.key?(key)
@@ -1,5 +1,5 @@
1
1
  require "pathname"
2
- require_relative "../workspace"
2
+ require_relative "../workspace/workspace"
3
3
  require_relative "base"
4
4
 
5
5
  # Namespace for the Kward CLI agent runtime.
@@ -16,23 +16,32 @@ module Kward
16
16
  SKIP_DIRECTORIES = %w[.git .yardoc _yardoc node_modules vendor tmp log coverage dist build .bundle].freeze
17
17
 
18
18
  # Builds the tool schema and stores the execution dependency.
19
- def initialize(workspace:)
20
- @workspace = workspace
19
+ def initialize(workspace:, workspace_targets: nil)
20
+ configure_workspace_targets(workspace, workspace_targets)
21
21
  super(
22
22
  "context_for_task",
23
23
  "Build focused workspace context for a task from outlines and matching excerpts within a byte budget.",
24
- properties: {
24
+ properties: targeted_properties(
25
25
  budget: { type: "integer", description: "Approximate byte budget for the returned context. Default 4000, maximum 20000." },
26
26
  paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative files or directories to focus." },
27
27
  task: { type: "string", description: "Task or question to gather context for." }
28
- },
28
+ ),
29
29
  required: ["task"]
30
30
  )
31
31
  end
32
32
 
33
33
  # Executes focused context retrieval.
34
- def call(args, _conversation, cancellation: nil)
34
+ def call(args, conversation, cancellation: nil)
35
35
  cancellation&.raise_if_cancelled!
36
+ selected_workspace = workspace_for(args)
37
+ unless selected_workspace.equal?(@workspace)
38
+ return self.class.new(workspace: selected_workspace).call(
39
+ @workspace_targets.without_target(args),
40
+ conversation,
41
+ cancellation: cancellation
42
+ )
43
+ end
44
+
36
45
  task = argument(args, :task, "").to_s.strip
37
46
  return "Error: task is required" if task.empty?
38
47
 
@@ -0,0 +1,85 @@
1
+ require "time"
2
+ require_relative "base"
3
+
4
+ # Namespace for the Kward CLI agent runtime.
5
+ module Kward
6
+ # Model-callable date and time utilities.
7
+ module Tools
8
+ class DateTime < Base
9
+ OFFSET_PATTERN = /\A(?:Z|[+-](?:0\d|1[0-4]):[0-5]\d)\z/.freeze
10
+ TIMESTAMP_OFFSET_PATTERN = /(?:Z|[+-]\d{2}:?\d{2})\z/i.freeze
11
+
12
+ def initialize
13
+ super(
14
+ "datetime",
15
+ "Get the current date and time, or add signed whole seconds to an ISO 8601 timestamp. Current time uses the host's local timezone unless a UTC offset is supplied. Arithmetic preserves the timestamp's offset; offsets do not include daylight-saving rules.",
16
+ properties: {
17
+ operation: {
18
+ type: "string",
19
+ enum: %w[current_time add_seconds],
20
+ description: "Operation to perform."
21
+ },
22
+ timezone_offset: {
23
+ type: "string",
24
+ description: "Optional UTC offset for current_time, formatted as +HH:MM, -HH:MM, or Z."
25
+ },
26
+ timestamp: {
27
+ type: "string",
28
+ description: "ISO 8601 timestamp with an explicit UTC offset, required for add_seconds."
29
+ },
30
+ seconds: {
31
+ type: "integer",
32
+ description: "Signed whole number of seconds to add, required for add_seconds."
33
+ }
34
+ },
35
+ required: ["operation"]
36
+ )
37
+ end
38
+
39
+ def call(args, _conversation, cancellation: nil)
40
+ cancellation&.raise_if_cancelled!
41
+
42
+ case argument(args, :operation)
43
+ when "current_time"
44
+ current_time(args)
45
+ when "add_seconds"
46
+ add_seconds(args)
47
+ else
48
+ "Error: operation must be current_time or add_seconds"
49
+ end
50
+ rescue ArgumentError, RangeError, TypeError => e
51
+ "Error: #{e.message}"
52
+ end
53
+
54
+ private
55
+
56
+ def current_time(args)
57
+ offset = argument(args, :timezone_offset)
58
+ time = Time.now
59
+ time = time.getlocal(validated_offset(offset)) unless offset.nil?
60
+ "Current date/time: #{time.iso8601}"
61
+ end
62
+
63
+ def add_seconds(args)
64
+ timestamp = argument(args, :timestamp)
65
+ seconds = argument(args, :seconds)
66
+ unless timestamp.is_a?(String) && TIMESTAMP_OFFSET_PATTERN.match?(timestamp)
67
+ raise ArgumentError, "timestamp must be an ISO 8601 string with a UTC offset"
68
+ end
69
+ raise ArgumentError, "seconds must be an integer" unless seconds.is_a?(Integer)
70
+
71
+ "Result: #{(Time.iso8601(timestamp) + seconds).iso8601}"
72
+ end
73
+
74
+ def validated_offset(offset)
75
+ outside_iso_range = offset.is_a?(String) &&
76
+ offset.start_with?("+14:", "-14:") && offset[-2, 2] != "00"
77
+ unless offset.is_a?(String) && OFFSET_PATTERN.match?(offset) && !outside_iso_range
78
+ raise ArgumentError, "timezone_offset must be Z or an offset between -14:00 and +14:00"
79
+ end
80
+
81
+ offset == "Z" ? "+00:00" : offset
82
+ end
83
+ end
84
+ end
85
+ end
@@ -7,12 +7,12 @@ module Kward
7
7
  # Tool wrapper for exact block replacement edits.
8
8
  class EditFile < Base
9
9
  # Builds the tool schema and stores the execution dependency.
10
- def initialize(workspace:)
11
- @workspace = workspace
10
+ def initialize(workspace:, workspace_targets: nil)
11
+ configure_workspace_targets(workspace, workspace_targets)
12
12
  super(
13
13
  "edit_file",
14
14
  "Edit a read workspace file by exact replacements. Each old_text must match once; edits must not overlap.",
15
- properties: {
15
+ properties: targeted_properties(
16
16
  path: { type: "string", description: "Workspace-relative path." },
17
17
  edits: {
18
18
  type: "array",
@@ -27,7 +27,7 @@ module Kward
27
27
  additionalProperties: false
28
28
  }
29
29
  }
30
- },
30
+ ),
31
31
  required: ["path", "edits"]
32
32
  )
33
33
  end
@@ -37,8 +37,11 @@ module Kward
37
37
  path = argument(args, :path, "")
38
38
  edits = argument(args, :edits, [])
39
39
 
40
- result = @workspace.edit_file(path, edits, read_paths: conversation.read_paths)
41
- conversation.refresh_system_message! if agents_file_changed?(@workspace, path, result)
40
+ workspace = workspace_for(args)
41
+ result = workspace.edit_file(path, edits, read_paths: conversation.read_paths)
42
+ if workspace.equal?(@workspace) && agents_file_changed?(workspace, path, result)
43
+ conversation.refresh_system_message!
44
+ end
42
45
  result
43
46
  end
44
47
  end
@@ -0,0 +1,36 @@
1
+ require_relative "base"
2
+ require_relative "../model/codex_images"
3
+ require_relative "../generated_images"
4
+
5
+ module Kward
6
+ module Tools
7
+ # Generates a preview, never a workspace file. The frontend owns export.
8
+ class GenerateImage < Base
9
+ NAME = "generate_image".freeze
10
+ MAX_PROMPT_BYTES = 16_384
11
+
12
+ def initialize(client:, images:)
13
+ super(NAME, "Generate one PNG when the user asks to create an image. Describe what to draw, not a destination. Kward presents the preview and the user decides whether and where to save it.",
14
+ properties: { "prompt" => { type: "string", description: "What to draw." } }, required: ["prompt"])
15
+ @client = client
16
+ @images = images
17
+ end
18
+
19
+ def call(args, conversation, cancellation: nil, provider: nil, turn_id: nil)
20
+ prompt = args["prompt"] || args[:prompt]
21
+ unless prompt.is_a?(String) && !prompt.strip.empty? && prompt.bytesize <= MAX_PROMPT_BYTES
22
+ return "Error: provide a non-empty image prompt of at most #{MAX_PROMPT_BYTES} bytes."
23
+ end
24
+ return "Error: image generation requires a Codex turn." unless provider == "Codex"
25
+
26
+ bytes = @client.generate_codex_image(prompt, turn_id: turn_id, cancellation: cancellation)
27
+ cancellation&.raise_if_cancelled!
28
+ image = @images.add(conversation, bytes, cancellation: cancellation)
29
+ yield image if block_given?
30
+ "Image generated. The preview is ready for the user to save or discard. No project file was written."
31
+ rescue CodexImages::Error, GeneratedImages::Error => e
32
+ "Error: #{e.message}"
33
+ end
34
+ end
35
+ end
36
+ end
@@ -5,15 +5,18 @@ module Kward
5
5
  module Tools
6
6
  # Tool wrapper for the trusted host-side Git commit operation.
7
7
  class GitCommit < Base
8
- def initialize(committer:)
8
+ def initialize(committer:, workspace_targets: nil)
9
9
  @committer = committer
10
+ @workspace_targets = workspace_targets
11
+ properties = {
12
+ message: { type: "string", description: "Commit message." },
13
+ paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative paths to include." }
14
+ }
15
+ properties = workspace_targets.properties(properties) if workspace_targets
10
16
  super(
11
17
  "git_commit",
12
- "Stage and commit changes in the active worktree. Omit paths to include all current changes.",
13
- properties: {
14
- message: { type: "string", description: "Commit message." },
15
- paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative paths to include." }
16
- },
18
+ "Stage and commit changes in the selected worktree (active by default). Omit paths to include all current changes.",
19
+ properties: properties,
17
20
  required: ["message"]
18
21
  )
19
22
  end
@@ -27,7 +30,10 @@ module Kward
27
30
  return "Error: paths must contain strings" if paths && paths.any? { |path| !path.is_a?(String) }
28
31
 
29
32
  paths = nil if paths&.empty?
30
- result = @committer.call(message: message, paths: paths)
33
+ target = @workspace_targets&.target_name(args)
34
+ options = { message: message, paths: paths }
35
+ options[:target] = target if target && target != WorkspaceTargets::ACTIVE
36
+ result = @committer.call(**options)
31
37
  output = result[:output].to_s.strip
32
38
  return "Git commit succeeded\n#{output}" if result[:success]
33
39
 
@@ -7,19 +7,19 @@ module Kward
7
7
  # Tool wrapper for listing workspace directory entries.
8
8
  class ListDirectory < Base
9
9
  # Builds the tool schema and stores the execution dependency.
10
- def initialize(workspace:)
11
- @workspace = workspace
10
+ def initialize(workspace:, workspace_targets: nil)
11
+ configure_workspace_targets(workspace, workspace_targets)
12
12
  super(
13
13
  "list_directory",
14
14
  "List workspace directory entries.",
15
- properties: { path: { type: "string", description: "Workspace-relative directory." } },
15
+ properties: targeted_properties(path: { type: "string", description: "Workspace-relative directory." }),
16
16
  required: ["path"]
17
17
  )
18
18
  end
19
19
 
20
20
  # Executes the tool and returns model-facing output text.
21
21
  def call(args, _conversation, cancellation: nil)
22
- @workspace.list_directory(argument(args, :path, "."))
22
+ workspace_for(args).list_directory(argument(args, :path, "."))
23
23
  end
24
24
  end
25
25
  end
@@ -0,0 +1,41 @@
1
+ require_relative "base"
2
+
3
+ # Namespace for the Kward CLI agent runtime.
4
+ module Kward
5
+ # Model-callable tool wrappers and their argument schemas.
6
+ module Tools
7
+ # Adapts a trusted plugin tool registration to the normal tool interface.
8
+ class PluginTool < Base
9
+ attr_reader :plugin_path
10
+
11
+ def initialize(registration:, context_factory:)
12
+ @description = registration.description
13
+ @parameters = registration.schema
14
+ @plugin_path = registration.path
15
+ @handler = registration.handler
16
+ @context_factory = context_factory
17
+ super(registration.name, registration.description)
18
+ end
19
+
20
+ # Returns the strict JSON schema declared by the plugin.
21
+ def schema
22
+ {
23
+ type: "function",
24
+ function: {
25
+ name: name,
26
+ description: @description,
27
+ parameters: @parameters
28
+ }
29
+ }
30
+ end
31
+
32
+ # Executes trusted plugin code with parsed model arguments and scoped context.
33
+ def call(args, conversation, cancellation: nil)
34
+ context = @context_factory.call(conversation, cancellation)
35
+ result = @handler.call(args, context)
36
+ cancellation&.raise_if_cancelled!
37
+ result.to_s
38
+ end
39
+ end
40
+ end
41
+ end
@@ -1,5 +1,5 @@
1
1
  require_relative "base"
2
- require_relative "../shell_prompt_session"
2
+ require_relative "../shell/prompt_session"
3
3
 
4
4
  # Namespace for the Kward agent runtime.
5
5
  module Kward
@@ -7,18 +7,18 @@ module Kward
7
7
  # Tool wrapper for bounded workspace file reads.
8
8
  class ReadFile < Base
9
9
  # Builds the tool schema and stores the execution dependency.
10
- def initialize(workspace:)
11
- @workspace = workspace
10
+ def initialize(workspace:, workspace_targets: nil)
11
+ configure_workspace_targets(workspace, workspace_targets)
12
12
  super(
13
13
  "read_file",
14
14
  "Read a workspace text file. Output is capped; use offset/limit or mode to control context budget.",
15
- properties: {
15
+ properties: targeted_properties(
16
16
  path: { type: "string", description: "Workspace-relative path." },
17
17
  limit: { type: "integer", description: "Maximum lines to return." },
18
18
  max_bytes: { type: "integer", description: "Optional byte budget for this read, capped by Kward's workspace read limit." },
19
19
  mode: { type: "string", enum: %w[preview outline range full], description: "Context mode. preview returns a short slice, outline returns source declarations, range reads offset/limit, full reads until Kward's cap." },
20
20
  offset: { type: "integer", description: "1-indexed start line." }
21
- },
21
+ ),
22
22
  required: ["path"]
23
23
  )
24
24
  end
@@ -30,8 +30,9 @@ module Kward
30
30
  limit = argument(args, :limit)
31
31
  mode = argument(args, :mode)
32
32
  max_bytes = argument(args, :max_bytes)
33
- content = @workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
34
- conversation.mark_read(@workspace.resolved_path(path)) unless content.start_with?("Error:")
33
+ workspace = workspace_for(args)
34
+ content = workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
35
+ conversation.mark_read(workspace.resolved_path(path)) unless content.start_with?("Error:")
35
36
  content
36
37
  end
37
38
  end