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
@@ -5,19 +5,24 @@ require_relative "ask_user_question"
5
5
  require_relative "code_search"
6
6
  require_relative "context_budget_stats"
7
7
  require_relative "context_for_task"
8
+ require_relative "datetime"
8
9
  require_relative "edit_file"
9
10
  require_relative "fetch_content"
10
11
  require_relative "fetch_raw"
11
12
  require_relative "git_commit"
13
+ require_relative "generate_image"
12
14
  require_relative "list_directory"
13
15
  require_relative "mcp_tool"
16
+ require_relative "plugin_tool"
14
17
  require_relative "read_file"
15
18
  require_relative "read_skill"
16
19
  require_relative "run_shell_command"
17
20
  require_relative "prepare_shell_command"
18
21
  require_relative "summarize_file_structure"
22
+ require_relative "typesafe_evaluate"
19
23
  require_relative "retrieve_tool_output"
20
24
  require_relative "web_search"
25
+ require_relative "workspace_targets"
21
26
  require_relative "write_file"
22
27
  require_relative "open_editor"
23
28
  require_relative "replace_editor_buffer"
@@ -29,7 +34,7 @@ require_relative "../mcp/server_config"
29
34
  require_relative "../permissions/policy"
30
35
  require_relative "../telemetry/logger"
31
36
  require_relative "../tool_output_compactor"
32
- require_relative "../workspace"
37
+ require_relative "../workspace/workspace"
33
38
 
34
39
  # Namespace for the Kward CLI agent runtime.
35
40
  module Kward
@@ -66,6 +71,32 @@ module Kward
66
71
  retrieve_tool_output
67
72
  ].freeze
68
73
 
74
+ TARGETED_WORKSPACE_TOOLS = %w[
75
+ list_directory
76
+ read_file
77
+ write_file
78
+ edit_file
79
+ run_shell_command
80
+ summarize_file_structure
81
+ context_for_task
82
+ git_commit
83
+ ].freeze
84
+
85
+ BUILTIN_TOOL_NAMES = (CORE_TOOL_NAMES + %w[
86
+ git_commit
87
+ generate_image
88
+ web_search
89
+ fetch_content
90
+ fetch_raw
91
+ read_skill
92
+ ask_user_question
93
+ replace_editor_buffer
94
+ open_editor
95
+ prepare_shell_command
96
+ typesafe_evaluate
97
+ datetime
98
+ ]).freeze
99
+
69
100
  # Tool schemas advertised to the model for the current frontend and config.
70
101
  #
71
102
  # @return [Array<Hash>] tool schemas currently advertised to the model
@@ -74,6 +105,7 @@ module Kward
74
105
  # Builds tool objects and the schema list for the current frontend/config.
75
106
  #
76
107
  # @param workspace [Workspace] filesystem/shell boundary used by local tools
108
+ # @param workspace_targets [Tools::WorkspaceTargets, nil] additional host-scoped worktree roles
77
109
  # @param prompt [Object, nil] interactive prompt bridge; tools such as
78
110
  # `ask_user_question` and `open_editor` are advertised only when supported
79
111
  # @param web_search [WebSearch] live web search implementation
@@ -82,12 +114,15 @@ module Kward
82
114
  # @param web_search_enabled [Boolean, nil] override for web search exposure
83
115
  # @param skills [Array<ConfigFiles::Skill>, nil] override discovered skills
84
116
  # @param ask_user_question_enabled [Boolean, nil] override question exposure
85
- def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, editor_prompt_session: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil, git_committer: nil)
117
+ # @param plugin_tools [Array<PluginRegistry::Tool>] trusted plugin tool registrations
118
+ def initialize(workspace: Workspace.new, workspace_targets: nil, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, editor_prompt_session: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, plugin_tools: [], typesafe_client: TypeSafeClient.new, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil, git_committer: nil, image_client: nil, generated_images: nil)
86
119
  @workspace = workspace
120
+ @workspace_targets = workspace_targets || Tools::WorkspaceTargets.new(active: workspace)
87
121
  @prompt = prompt
88
122
  @web_search = web_search
89
123
  @web_fetch = web_fetch
90
124
  @code_search = code_search
125
+ @typesafe_client = typesafe_client
91
126
  @skills = skills
92
127
  @web_search_enabled = web_search_enabled
93
128
  @ask_user_question_enabled = ask_user_question_enabled
@@ -97,12 +132,15 @@ module Kward
97
132
  @tool_output_compactor = tool_output_compactor
98
133
  @telemetry_logger = telemetry_logger
99
134
  @context_budget_meter = context_budget_meter
135
+ @plugin_tools = Array(plugin_tools)
100
136
  @tool_approval = tool_approval
101
137
  @approval_for_allowed_tools = approval_for_allowed_tools == true
102
138
  @permission_policy = permission_policy || Permissions::Policy.from_config(ConfigFiles.read_config)
103
139
  @hook_manager = hook_manager
104
140
  @hook_context = hook_context
105
141
  @git_committer = git_committer
142
+ @generated_images = generated_images
143
+ @image_tool = Tools::GenerateImage.new(client: image_client, images: generated_images) if generated_images && image_client.respond_to?(:generate_codex_image)
106
144
  @mcp_clients = if mcp_clients
107
145
  mcp_clients
108
146
  elsif @allowed_tool_names
@@ -114,6 +152,16 @@ module Kward
114
152
  @schemas = build_schema_tools.map { |tool| schema_with_metadata(tool) }.freeze
115
153
  end
116
154
 
155
+ # Replaces plugin registrations while preserving this registry's frontend,
156
+ # workspace, permission, hook, and execution-profile restrictions.
157
+ def replace_plugin_tools!(plugin_tools)
158
+ @plugin_tools = Array(plugin_tools)
159
+ @plugin_tool_values = nil
160
+ @tools = build_tools.freeze
161
+ @schemas = build_schema_tools.map { |tool| schema_with_metadata(tool) }.freeze
162
+ self
163
+ end
164
+
117
165
  # Builds a registry scoped to one editor prompt turn.
118
166
  #
119
167
  # Editor prompts may inspect the workspace, but their only write operation
@@ -154,16 +202,20 @@ module Kward
154
202
  # @param tool_call [Hash] model tool call payload
155
203
  # @param conversation [Conversation] active conversation
156
204
  # @return [String] tool output content appended to the conversation
157
- def dispatch(tool_call, conversation, cancellation: nil)
205
+ def dispatch(tool_call, conversation, cancellation: nil, image_context: nil, &image_ready)
158
206
  cancellation&.raise_if_cancelled!
159
207
  name = ToolCall.name(tool_call)
160
208
  args = ToolCall.arguments(tool_call)
161
209
  tool = @tools[name]
210
+ execute = -> { execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation, image_context: image_context, &image_ready) }
162
211
 
163
212
  original_content = if tool
164
213
  before_tool = run_hook("tool_call_before", conversation, payload: tool_payload(name, args, tool_call))
165
214
  args = hook_arguments(before_tool, args)
166
- if before_tool.denied?
215
+ target_error = workspace_target_error(name, args)
216
+ if target_error
217
+ target_error
218
+ elsif before_tool.denied?
167
219
  hook_denied_content(before_tool, "tool call denied: #{name}")
168
220
  elsif before_tool.approval_required? && hook_approval_denied?(before_tool, tool_call, name, args, cancellation)
169
221
  hook_denied_content(before_tool, "tool call approval denied: #{name}")
@@ -175,16 +227,16 @@ module Kward
175
227
  approval = permission_approval_result(tool_call, name, args, cancellation)
176
228
  if approval == :allow_for_session
177
229
  @permission_policy.allow_for_session!(name)
178
- execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
230
+ execute.call
179
231
  elsif approval == true
180
- execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
232
+ execute.call
181
233
  else
182
234
  approval_denied_content(approval, name)
183
235
  end
184
236
  elsif @approval_for_allowed_tools && tool_approval_denied?(tool_call, name, args, cancellation)
185
237
  "Declined: tool execution denied by user: #{name}"
186
238
  else
187
- execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
239
+ execute.call
188
240
  end
189
241
  end
190
242
  else
@@ -221,6 +273,18 @@ module Kward
221
273
  # @param name [String, #to_s] exposed tool name
222
274
  # @return [Hash] source, display name, and optional MCP identity
223
275
  # @api public
276
+ def schemas_for(provider)
277
+ return @schemas if provider.to_s.casecmp?("codex")
278
+
279
+ @schemas.reject { |schema| ToolCall.name(schema) == Tools::GenerateImage::NAME }
280
+ end
281
+
282
+ def discard_generated_image(conversation, id)
283
+ @generated_images.discard(conversation, id)
284
+ rescue GeneratedImages::Error
285
+ nil
286
+ end
287
+
224
288
  def metadata_for(name)
225
289
  tool = @tools[name.to_s]
226
290
  return unknown_tool_metadata(name) unless tool
@@ -254,6 +318,8 @@ module Kward
254
318
  case tool
255
319
  when Tools::MCPTool
256
320
  "mcp"
321
+ when Tools::PluginTool
322
+ "plugin"
257
323
  when Tools::WebSearch, Tools::FetchContent, Tools::FetchRaw
258
324
  "web"
259
325
  when Tools::ReadSkill
@@ -322,11 +388,15 @@ module Kward
322
388
  )
323
389
  end
324
390
 
325
- def execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
391
+ def execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation, image_context:, &image_ready)
326
392
  args = run_shell_before_hooks(name, args, tool_call, conversation, cancellation)
327
393
  run_file_change_before_hooks(name, args, tool_call, conversation, cancellation)
328
394
  run_mcp_before_hooks(name, args, tool_call, conversation, cancellation)
329
- content = tool.call(args, conversation, cancellation: cancellation)
395
+ content = if tool.is_a?(Tools::GenerateImage)
396
+ tool.call(args, conversation, cancellation: cancellation, **(image_context || {}), &image_ready)
397
+ else
398
+ tool.call(args, conversation, cancellation: cancellation)
399
+ end
330
400
  run_mcp_after_hooks(name, args, content, conversation)
331
401
  run_shell_after_hooks(name, args, content, conversation)
332
402
  run_file_change_after_hooks(name, args, content, conversation)
@@ -491,6 +561,13 @@ module Kward
491
561
  (metadata[:source] || metadata["source"]).to_s == "mcp"
492
562
  end
493
563
 
564
+ def workspace_target_error(name, args)
565
+ return nil unless TARGETED_WORKSPACE_TOOLS.include?(name.to_s)
566
+ return nil if @workspace_targets.valid?(args)
567
+
568
+ "Error: Unknown workspace target: #{@workspace_targets.target_name(args)}"
569
+ end
570
+
494
571
  def permission_approval_result(tool_call, name, args, cancellation)
495
572
  return false unless @tool_approval
496
573
 
@@ -514,6 +591,11 @@ module Kward
514
591
  tools = all_tools
515
592
  tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names
516
593
  tools.each_with_object({}) do |tool, result|
594
+ if tool.is_a?(Tools::PluginTool) && (BUILTIN_TOOL_NAMES.include?(tool.name) || result.key?(tool.name))
595
+ source = tool.plugin_path.to_s.empty? ? "" : " (#{tool.plugin_path})"
596
+ ConfigFiles.emit_warning("Warning: skipping Kward plugin tool #{tool.name}#{source}: duplicate tool name")
597
+ next
598
+ end
517
599
  raise ArgumentError, "Duplicate tool name: #{tool.name}" if result.key?(tool.name)
518
600
 
519
601
  result[tool.name] = tool
@@ -521,13 +603,16 @@ module Kward
521
603
  end
522
604
 
523
605
  def build_schema_tools
524
- tools = @tools.values_at(*CORE_TOOL_NAMES)
606
+ tools = @tools.values_at(*CORE_TOOL_NAMES, Tools::GenerateImage::NAME)
525
607
  tools << @tools["replace_editor_buffer"] if @tools["replace_editor_buffer"]
526
608
  tools << @tools["open_editor"] if @tools["open_editor"]
527
609
  tools << @tools["prepare_shell_command"] if @tools["prepare_shell_command"]
528
610
  tools << @tools["git_commit"] if @tools["git_commit"]
529
611
  tools.concat(@tools.values_at("web_search", "fetch_content", "fetch_raw")) if web_search_available?
530
612
  tools.concat(@tools.values.select { |tool| tool.is_a?(Tools::MCPTool) })
613
+ tools.concat(@tools.values.select { |tool| tool.is_a?(Tools::PluginTool) })
614
+ tools << @tools["datetime"] if @tools["datetime"]
615
+ tools << @tools["typesafe_evaluate"] if @tools["typesafe_evaluate"]
531
616
  tools << @tools["read_skill"] if skills_available?
532
617
  tools << @tools["ask_user_question"] if ask_user_question_available?
533
618
  tools.compact
@@ -535,26 +620,29 @@ module Kward
535
620
 
536
621
  def all_tools
537
622
  tools = core_tools
538
- tools << Tools::GitCommit.new(committer: @git_committer) if @git_committer
539
- tools + [
623
+ tools << @image_tool if @image_tool
624
+ tools << Tools::GitCommit.new(committer: @git_committer, workspace_targets: @workspace_targets) if @git_committer
625
+ (tools + [
626
+ (Tools::TypeSafeEvaluate.new(client: @typesafe_client) if @typesafe_client&.available?),
540
627
  Tools::WebSearch.new(web_search: @web_search),
541
628
  Tools::FetchContent.new(web_fetch: @web_fetch),
542
629
  Tools::FetchRaw.new(web_fetch: @web_fetch),
543
630
  Tools::ReadSkill.new(skills: discovered_skills),
544
- Tools::AskUserQuestion.new(prompt: @prompt)
545
- ] + mcp_tool_values
631
+ Tools::AskUserQuestion.new(prompt: @prompt),
632
+ Tools::DateTime.new
633
+ ]).compact + mcp_tool_values + plugin_tool_values
546
634
  end
547
635
 
548
636
  def core_tools
549
637
  tools = [
550
- Tools::ListDirectory.new(workspace: @workspace),
551
- Tools::ReadFile.new(workspace: @workspace),
552
- Tools::WriteFile.new(workspace: @workspace),
553
- Tools::EditFile.new(workspace: @workspace),
638
+ Tools::ListDirectory.new(workspace: @workspace, workspace_targets: @workspace_targets),
639
+ Tools::ReadFile.new(workspace: @workspace, workspace_targets: @workspace_targets),
640
+ Tools::WriteFile.new(workspace: @workspace, workspace_targets: @workspace_targets),
641
+ Tools::EditFile.new(workspace: @workspace, workspace_targets: @workspace_targets),
554
642
  shell_command_tool,
555
643
  Tools::CodeSearch.new(code_search: @code_search),
556
- Tools::SummarizeFileStructure.new(workspace: @workspace),
557
- Tools::ContextForTask.new(workspace: @workspace),
644
+ Tools::SummarizeFileStructure.new(workspace: @workspace, workspace_targets: @workspace_targets),
645
+ Tools::ContextForTask.new(workspace: @workspace, workspace_targets: @workspace_targets),
558
646
  Tools::ContextBudgetStats.new(context_budget_meter: @context_budget_meter),
559
647
  Tools::RetrieveToolOutput.new
560
648
  ]
@@ -568,7 +656,7 @@ module Kward
568
656
  if @shell_prompt_session
569
657
  Tools::RunShellCommand.new(shell_prompt_session: @shell_prompt_session)
570
658
  else
571
- Tools::RunShellCommand.new(workspace: @workspace)
659
+ Tools::RunShellCommand.new(workspace: @workspace, workspace_targets: @workspace_targets)
572
660
  end
573
661
  end
574
662
 
@@ -611,6 +699,27 @@ module Kward
611
699
  @mcp_tool_values ||= build_mcp_tools
612
700
  end
613
701
 
702
+ def plugin_tool_values
703
+ @plugin_tool_values ||= @plugin_tools.map do |registration|
704
+ Tools::PluginTool.new(
705
+ registration: registration,
706
+ context_factory: method(:plugin_tool_context)
707
+ )
708
+ end
709
+ end
710
+
711
+ def plugin_tool_context(conversation, cancellation)
712
+ if @hook_context.respond_to?(:for_tool)
713
+ @hook_context.for_tool(conversation: conversation, cancellation: cancellation)
714
+ else
715
+ PluginRegistry::Context.new(
716
+ conversation: conversation,
717
+ workspace_root: @workspace.respond_to?(:root) ? @workspace.root.to_s : Dir.pwd,
718
+ cancellation: cancellation
719
+ )
720
+ end
721
+ end
722
+
614
723
  def build_mcp_tools
615
724
  Array(@mcp_clients).flat_map do |client|
616
725
  client.list_tools.map do |tool|
@@ -1,5 +1,5 @@
1
1
  require_relative "base"
2
- require_relative "../workspace"
2
+ require_relative "../workspace/workspace"
3
3
 
4
4
  # Namespace for the Kward CLI agent runtime.
5
5
  module Kward
@@ -8,11 +8,11 @@ module Kward
8
8
  # Tool wrapper for bounded shell commands in the workspace or active shell.
9
9
  class RunShellCommand < Base
10
10
  # Builds the tool schema and stores the execution dependency.
11
- def initialize(workspace: nil, shell_prompt_session: nil)
11
+ def initialize(workspace: nil, workspace_targets: nil, shell_prompt_session: nil)
12
12
  raise ArgumentError, "RunShellCommand requires a workspace or shell session" unless workspace || shell_prompt_session
13
13
  raise ArgumentError, "RunShellCommand accepts only one execution target" if workspace && shell_prompt_session
14
14
 
15
- @workspace = workspace
15
+ configure_workspace_targets(workspace, workspace_targets) if workspace
16
16
  @shell_prompt_session = shell_prompt_session
17
17
  description = shell_prompt_session ?
18
18
  "Run a bounded noninteractive command in the active embedded shell session." :
@@ -20,13 +20,15 @@ module Kward
20
20
  timeout_description = shell_prompt_session ?
21
21
  "Timeout seconds; defaults to the embedded shell setting." :
22
22
  "Timeout seconds; default 30."
23
+ properties = {
24
+ command: { type: "string", description: "Command to run." },
25
+ timeout_seconds: { type: "integer", description: timeout_description }
26
+ }
27
+ properties = targeted_properties(properties) if workspace
23
28
  super(
24
29
  "run_shell_command",
25
30
  description,
26
- properties: {
27
- command: { type: "string", description: "Command to run." },
28
- timeout_seconds: { type: "integer", description: timeout_description }
29
- },
31
+ properties: properties,
30
32
  required: ["command"]
31
33
  )
32
34
  end
@@ -43,7 +45,7 @@ module Kward
43
45
  if @shell_prompt_session
44
46
  @shell_prompt_session.run(command, timeout_seconds: timeout_seconds, cancellation: cancellation)
45
47
  else
46
- @workspace.run_shell_command(command, timeout_seconds: timeout_seconds, cancellation: cancellation)
48
+ workspace_for(args).run_shell_command(command, timeout_seconds: timeout_seconds, cancellation: cancellation)
47
49
  end
48
50
  end
49
51
  end
@@ -5,7 +5,7 @@ require "net/http"
5
5
  require "open3"
6
6
  require "pathname"
7
7
  require "uri"
8
- require_relative "../../path_guard"
8
+ require_relative "../../workspace/path_guard"
9
9
  require_relative "../../config_files"
10
10
  require_relative "web"
11
11
 
@@ -7,14 +7,14 @@ module Kward
7
7
  # Returns a compact symbol outline for a workspace source file.
8
8
  class SummarizeFileStructure < 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
  "summarize_file_structure",
14
14
  "Return a compact outline of classes, modules, methods, and functions in a workspace source file.",
15
- properties: {
15
+ properties: targeted_properties(
16
16
  path: { type: "string", description: "Workspace-relative source file path." }
17
- },
17
+ ),
18
18
  required: ["path"]
19
19
  )
20
20
  end
@@ -22,7 +22,7 @@ module Kward
22
22
  # Executes the structure summary tool.
23
23
  def call(args, _conversation, cancellation: nil)
24
24
  cancellation&.raise_if_cancelled!
25
- @workspace.summarize_file_structure(argument(args, :path, ""))
25
+ workspace_for(args).summarize_file_structure(argument(args, :path, ""))
26
26
  end
27
27
  end
28
28
  end
@@ -24,10 +24,13 @@ module Kward
24
24
  "web_search" => "web_search",
25
25
  "fetch_content" => "fetch_content",
26
26
  "fetch_raw" => "fetch_raw",
27
+ "generate_image" => "generate_image",
27
28
  "git_commit" => "git_commit",
28
29
  "read_skill" => "read_skill",
29
30
  "ask_user_question" => "ask_user_question",
30
- "open_editor" => "open_editor"
31
+ "open_editor" => "open_editor",
32
+ "typesafe_evaluate" => "typesafe_evaluate",
33
+ "datetime" => "datetime"
31
34
  }.freeze
32
35
 
33
36
  module_function
@@ -0,0 +1,81 @@
1
+ require "json"
2
+ require_relative "base"
3
+ require_relative "../model/typesafe_client"
4
+
5
+ module Kward
6
+ module Tools
7
+ # Evaluates bounded state with TypeSafe's typed decision model.
8
+ class TypeSafeEvaluate < Base
9
+ def initialize(client: TypeSafeClient.new)
10
+ @client = client
11
+ super(
12
+ "typesafe_evaluate",
13
+ "Evaluate text with TypeSafe and return typed decisions, probabilities, and confidence. Use for classification, scoring, routing, or verification; this does not generate text.",
14
+ properties: {
15
+ state: {
16
+ type: "string",
17
+ description: "The text or structured state to evaluate; do not include secrets unless explicitly requested."
18
+ },
19
+ model: {
20
+ type: "string",
21
+ description: "TypeSafe model ID or alias; defaults to jev-latest."
22
+ },
23
+ questions: {
24
+ type: "object",
25
+ description: "Named typed questions. Each value must be a noul, choice, or score question.",
26
+ additionalProperties: {
27
+ type: "object",
28
+ properties: {
29
+ type: { type: "string", enum: %w[noul choice score] },
30
+ instructions: { type: "string" },
31
+ criteria: { type: ["object", "array"] }
32
+ },
33
+ required: %w[type instructions],
34
+ additionalProperties: false
35
+ }
36
+ }
37
+ },
38
+ required: %w[state questions]
39
+ )
40
+ end
41
+
42
+ def call(args, _conversation, cancellation: nil)
43
+ state = argument(args, "state").to_s
44
+ questions = argument(args, "questions")
45
+ error = validate(state, questions)
46
+ return "Error: #{error}" if error
47
+
48
+ response = @client.evaluate(
49
+ state: state,
50
+ questions: questions,
51
+ model: argument(args, "model") || TypeSafeClient::DEFAULT_MODEL,
52
+ cancellation: cancellation
53
+ )
54
+ JSON.pretty_generate(response)
55
+ rescue TypeSafeClient::RequestError => e
56
+ "Error: #{e.message}"
57
+ rescue JSON::GeneratorError, TypeError => e
58
+ "Error: invalid TypeSafe response: #{e.message}"
59
+ end
60
+
61
+ private
62
+
63
+ def validate(state, questions)
64
+ return "state must be a non-empty string" if state.empty?
65
+ return "state exceeds #{TypeSafeClient::MAX_STATE_BYTES} bytes" if state.bytesize > TypeSafeClient::MAX_STATE_BYTES
66
+ return "questions must be an object" unless questions.is_a?(Hash)
67
+ return "questions must contain 1-#{TypeSafeClient::MAX_QUESTIONS} entries" if questions.empty? || questions.length > TypeSafeClient::MAX_QUESTIONS
68
+
69
+ questions.each do |name, question|
70
+ return "question names must be non-empty strings" unless name.is_a?(String) && !name.empty?
71
+ return "question #{name.inspect} must be an object" unless question.is_a?(Hash)
72
+ type = argument(question, "type").to_s
73
+ return "question #{name.inspect} has unsupported type" unless %w[noul choice score].include?(type)
74
+ return "question #{name.inspect} needs instructions" if argument(question, "instructions").to_s.empty?
75
+ return "question #{name.inspect} needs criteria" if %w[choice score].include?(type) && !argument(question, "criteria")
76
+ end
77
+ nil
78
+ end
79
+ end
80
+ end
81
+ end
@@ -0,0 +1,58 @@
1
+ # Namespace for the Kward CLI agent runtime.
2
+ module Kward
3
+ # Model-callable tool wrappers and their argument schemas.
4
+ module Tools
5
+ # Resolves a small host-scoped set of workspace roles for local tools.
6
+ # Target names are supplied by trusted runtime orchestration, never by the
7
+ # model, so selecting a target cannot escape into an arbitrary filesystem
8
+ # path.
9
+ class WorkspaceTargets
10
+ ACTIVE = "active"
11
+
12
+ def initialize(active:, targets: {})
13
+ @workspaces = { ACTIVE => active }
14
+ targets.each do |name, workspace|
15
+ name = name.to_s
16
+ raise ArgumentError, "Workspace target name is required" if name.empty?
17
+ raise ArgumentError, "Workspace target #{ACTIVE.inspect} is reserved" if name == ACTIVE
18
+
19
+ @workspaces[name] = workspace
20
+ end
21
+ @workspaces.freeze
22
+ end
23
+
24
+ def workspace_for(args)
25
+ @workspaces.fetch(target_name(args)) do |name|
26
+ raise ArgumentError, "Unknown workspace target: #{name}"
27
+ end
28
+ end
29
+
30
+ def target_name(args)
31
+ value = if args.respond_to?(:key?)
32
+ args[:target] || args["target"]
33
+ end
34
+ value.to_s.empty? ? ACTIVE : value.to_s
35
+ end
36
+
37
+ def valid?(args)
38
+ @workspaces.key?(target_name(args))
39
+ end
40
+
41
+ def properties(properties)
42
+ return properties if @workspaces.length == 1
43
+
44
+ properties.merge(
45
+ target: {
46
+ type: "string",
47
+ enum: @workspaces.keys,
48
+ description: "Workspace role. Defaults to active; origin is the host repository worktree."
49
+ }
50
+ )
51
+ end
52
+
53
+ def without_target(args)
54
+ args.reject { |key, _value| key.to_s == "target" }
55
+ end
56
+ end
57
+ end
58
+ end
@@ -7,15 +7,15 @@ module Kward
7
7
  # Tool wrapper for guarded full-file writes.
8
8
  class WriteFile < 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
  "write_file",
14
14
  "Write a workspace file. Existing files must be read first.",
15
- properties: {
15
+ properties: targeted_properties(
16
16
  path: { type: "string", description: "Workspace-relative path." },
17
17
  content: { type: "string", description: "Complete file content." }
18
- },
18
+ ),
19
19
  required: ["path", "content"]
20
20
  )
21
21
  end
@@ -25,8 +25,11 @@ module Kward
25
25
  path = argument(args, :path, "")
26
26
  content = argument(args, :content, "")
27
27
 
28
- result = @workspace.write_file(path, content, read_paths: conversation.read_paths)
29
- conversation.refresh_system_message! if agents_file_changed?(@workspace, path, result)
28
+ workspace = workspace_for(args)
29
+ result = workspace.write_file(path, content, read_paths: conversation.read_paths)
30
+ if workspace.equal?(@workspace) && agents_file_changed?(workspace, path, result)
31
+ conversation.refresh_system_message!
32
+ end
30
33
  result
31
34
  end
32
35
  end
@@ -1,5 +1,5 @@
1
1
  require "pathname"
2
- require_relative "path_guard"
2
+ require_relative "../workspace/path_guard"
3
3
 
4
4
  # Namespace for the Kward CLI agent runtime.
5
5
  module Kward
@@ -1,5 +1,7 @@
1
- require_relative "message_access"
2
- require_relative "message_text"
1
+ require_relative "../message_access"
2
+ require_relative "../message_text"
3
+ require_relative "../config_files"
4
+ require_relative "turn_summary_formatter"
3
5
 
4
6
  # Namespace for the Kward CLI agent runtime.
5
7
  module Kward
@@ -11,6 +13,7 @@ module Kward
11
13
 
12
14
  def render
13
15
  lines = ["# Kward Session", ""]
16
+ stats_mode = ConfigFiles.transcript_turn_stats
14
17
  @conversation.messages.each do |message|
15
18
  role = MessageAccess.role(message)
16
19
  next if role == "system"
@@ -21,6 +24,11 @@ module Kward
21
24
  lines << ""
22
25
  lines << markdown_content(message_markdown_content(message, role))
23
26
  lines << ""
27
+ stats = TurnSummaryFormatter.render(MessageAccess.value(message, :turn_summary), mode: stats_mode)
28
+ unless stats.empty?
29
+ lines.concat(stats.lines.map { |line| "> #{line.chomp}" })
30
+ lines << ""
31
+ end
24
32
  end
25
33
  lines.join("\n")
26
34
  end