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
@@ -0,0 +1,400 @@
1
+ # Core configuration paths, persistence, and shared configuration values.
2
+ require_relative "paths"
3
+
4
+ module Kward
5
+ module ConfigFiles
6
+ class ConfigError < StandardError
7
+ attr_reader :path, :format, :detail
8
+
9
+ def initialize(path:, format:, detail:)
10
+ @path = path
11
+ @format = format
12
+ @detail = detail
13
+ super("Invalid Kward config #{format}: #{path}: #{detail}")
14
+ end
15
+ end
16
+
17
+ MAX_SKILL_FILE_BYTES = 100_000
18
+ MAX_PROMPT_FILE_BYTES = 32 * 1024
19
+ DEFAULT_OVERLAY_SETTINGS = { "alignment" => "center", "width" => "maximum" }.freeze
20
+ PROJECT_BROWSER_ICON_THEMES = %w[off nerd-font].freeze
21
+ DEFAULT_PERSONAS = {
22
+ "characters" => [
23
+ {
24
+ "key" => "kward",
25
+ "label" => "Kward",
26
+ "instruction" => "Your name is Kward, the grim Andruid - robotic keeper of the Forest of Code, protecting the nature of good engineering principles. Speak like an old druid, be suspicious of everyone, but with good intent."
27
+ }
28
+ ],
29
+ "default" => "kward"
30
+ }.freeze
31
+ OVERLAY_ALIGNMENTS = %w[left center right].freeze
32
+ OVERLAY_WIDTHS = %w[capped maximum].freeze
33
+
34
+ Skill = Struct.new(:name, :description, :folder, :path, :license, :compatibility, :metadata, :allowed_tools, keyword_init: true)
35
+ PromptTemplate = Struct.new(:command, :description, :argument_hint, :body, :path, keyword_init: true) do
36
+ def expand(arguments)
37
+ body.gsub("$ARGUMENTS", arguments.to_s)
38
+ end
39
+ end
40
+
41
+ @skip_config = false
42
+ @ignore_local_instructions = false
43
+ @warning_sink = nil
44
+
45
+ module Core
46
+ extend self
47
+
48
+ def skip_config=(value)
49
+ @skip_config = value
50
+ end
51
+
52
+ def ignore_local_instructions=(value)
53
+ @ignore_local_instructions = value
54
+ end
55
+
56
+ def ignore_local_instructions?
57
+ @ignore_local_instructions == true
58
+ end
59
+
60
+ def warning_sink=(sink)
61
+ @warning_sink = sink
62
+ end
63
+
64
+ def warning_sink
65
+ @warning_sink
66
+ end
67
+
68
+ def skip_config?
69
+ @skip_config == true
70
+ end
71
+
72
+ # Directory that contains Kward's user config and adjacent prompt/skill
73
+ # data. Defaults to `~/.kward`, or the directory of `KWARD_CONFIG_PATH`.
74
+ #
75
+ # @return [String] expanded config directory path
76
+ def config_dir
77
+ ConfigPaths.config_dir
78
+ end
79
+
80
+ # @return [String] expanded JSON config file path
81
+ def config_path
82
+ File.expand_path(ENV["KWARD_CONFIG_PATH"] || File.join(config_dir, "config.json"))
83
+ end
84
+
85
+ # @return [String] directory containing reusable local caches
86
+ def cache_dir
87
+ File.join(config_dir, "cache")
88
+ end
89
+
90
+ # @return [String] embedded-shell rc config path
91
+ def kwshrc_path
92
+ File.join(config_dir, "kwshrc")
93
+ end
94
+
95
+ # @return [Array<String>] embedded-shell rc config paths in load order
96
+ def kwshrc_paths
97
+ Kwshrc.paths(kwshrc_path)
98
+ end
99
+
100
+ def workspace_hooks_path(root = Dir.pwd)
101
+ File.join(File.expand_path(root), ".kward", "hooks.json")
102
+ end
103
+
104
+ def trusted_workspace_hooks_path
105
+ File.join(config_dir, "trusted_workspace_hooks.json")
106
+ end
107
+
108
+ # Returns a fresh default config suitable for first-run persistence.
109
+ #
110
+ # @return [Hash] deep-mutable config defaults
111
+ def default_config
112
+ {
113
+ "personas" => JSON.parse(JSON.generate(DEFAULT_PERSONAS)),
114
+ "memory" => {
115
+ "enabled" => false,
116
+ "auto_summary" => false
117
+ },
118
+ "transcript" => {
119
+ "turn_stats" => "compact"
120
+ },
121
+ "composer" => {
122
+ "busy_help" => true,
123
+ "tab_keybindings" => "auto"
124
+ },
125
+ "editor" => {
126
+ "mode" => "modern",
127
+ "agent" => {},
128
+ "runners" => {},
129
+ "auto_indent" => true,
130
+ "auto_close_pairs" => true,
131
+ "soft_wrap" => true,
132
+ "bar_cursor" => true,
133
+ "line_numbers" => "absolute",
134
+ "diff_view" => "auto"
135
+ },
136
+ "overlay" => DEFAULT_OVERLAY_SETTINGS.dup,
137
+ "project_browser" => {
138
+ "icons" => "off"
139
+ },
140
+ "web_search" => {
141
+ "enabled" => true,
142
+ "provider" => "auto",
143
+ "allow_model_providers" => false
144
+ },
145
+ "updates" => {
146
+ "check" => true
147
+ },
148
+ "sessions" => {
149
+ "auto_resume" => false
150
+ },
151
+ "skills" => {
152
+ "trust_project" => false
153
+ },
154
+ "enforce_workspace_agents_file" => false,
155
+ "system_prompt" => {
156
+ "include_principles" => true
157
+ },
158
+ "mcpServers" => {},
159
+ "plugins" => {},
160
+ "transports" => {},
161
+ "tools" => {
162
+ "workspace_guardrails" => true
163
+ },
164
+ "permissions" => {
165
+ "enabled" => false,
166
+ "mode" => "ask"
167
+ },
168
+ "sandbox" => {
169
+ "mode" => "off",
170
+ "network" => "deny",
171
+ "writable_roots" => [],
172
+ "protect_git_metadata" => true
173
+ }
174
+ }
175
+ end
176
+
177
+ # Performs ensure default config for configuration file and path handling.
178
+ def ensure_default_config!(path = config_path)
179
+ path = File.expand_path(path)
180
+ return false if skip_config? && path == config_path
181
+ return false if File.exist?(path)
182
+
183
+ write_config(default_config, path)
184
+ true
185
+ end
186
+
187
+ def code_search_cache_dir
188
+ File.join(cache_dir, "code_search")
189
+ end
190
+
191
+ def openrouter_models_cache_path
192
+ File.join(cache_dir, "openrouter_models.json")
193
+ end
194
+
195
+ def model_catalog_cache_path(provider_id)
196
+ provider = provider_id.to_s.gsub(/[^a-z0-9_-]/i, "_")
197
+ raise ArgumentError, "Provider id must be a non-empty string" if provider.empty?
198
+
199
+ File.join(cache_dir, "models", "#{provider}.json")
200
+ end
201
+
202
+ def update_check_cache_path
203
+ File.join(cache_dir, "update_check.json")
204
+ end
205
+
206
+ def project_browser_state_path
207
+ File.join(cache_dir, "project_browser_state.json")
208
+ end
209
+
210
+ def prompt_history_path(cwd, config_dir: self.config_dir, kind: "prompt")
211
+ key = Digest::SHA256.hexdigest(canonical_workspace_root(cwd))[0, 24]
212
+ return File.join(config_dir, "history", "#{key}.jsonl") if kind.to_s == "prompt"
213
+
214
+ File.join(config_dir, "history", kind.to_s, "#{key}.jsonl")
215
+ end
216
+
217
+ # @return [String] directory containing structured memory files
218
+ def memory_dir
219
+ File.join(config_dir, "memory")
220
+ end
221
+
222
+ def memory_core_path
223
+ File.join(memory_dir, "core.json")
224
+ end
225
+
226
+ def memory_soft_path
227
+ File.join(memory_dir, "soft.jsonl")
228
+ end
229
+
230
+ def memory_events_path
231
+ File.join(memory_dir, "events.jsonl")
232
+ end
233
+
234
+ # Reads the JSON config file.
235
+ #
236
+ # Missing files are treated as an empty config. Invalid JSON raises a
237
+ # user-facing error that includes the file path. This method does not merge
238
+ # defaults; callers should apply feature-specific defaults at the point where
239
+ # behavior is decided.
240
+ #
241
+ # @param path [String] config file path
242
+ # @return [Hash] parsed config object
243
+ def read_config(path = config_path)
244
+ path = File.expand_path(path)
245
+ return {} if skip_config? && path == config_path
246
+ return {} unless File.exist?(path)
247
+
248
+ config = JSON.parse(File.read(path))
249
+ return config if config.is_a?(Hash)
250
+
251
+ raise ConfigError.new(path: path, format: "JSON", detail: "top-level value must be an object")
252
+ rescue JSON::ParserError => e
253
+ raise ConfigError.new(path: path, format: "JSON", detail: e.message)
254
+ end
255
+
256
+ # Writes config JSON using private file permissions.
257
+ #
258
+ # @param config [Hash] config object to persist
259
+ # @param path [String] config file path
260
+ def write_config(config, path = config_path)
261
+ path = File.expand_path(path)
262
+ raise "Cannot write Kward config while --skip-config is active: #{path}" if skip_config? && path == config_path
263
+
264
+ PrivateFile.write_json(path, config)
265
+ end
266
+
267
+ def lifecycle_hooks_config(workspace_root = Dir.pwd)
268
+ config = read_config
269
+ workspace_config = read_trusted_workspace_hooks_config(workspace_root)
270
+ return config if workspace_config.empty?
271
+
272
+ merge_hooks_config(config, workspace_config)
273
+ end
274
+
275
+ def read_trusted_workspace_hooks_config(workspace_root = Dir.pwd)
276
+ path = workspace_hooks_path(workspace_root)
277
+ return {} unless workspace_hooks_trusted?(workspace_root)
278
+
279
+ read_config(path)
280
+ end
281
+
282
+ def workspace_hooks_trusted?(workspace_root = Dir.pwd)
283
+ path = workspace_hooks_path(workspace_root)
284
+ return false unless File.file?(path)
285
+
286
+ trusted = read_trusted_workspace_hooks
287
+ trusted[File.expand_path(path)] == workspace_hooks_digest(workspace_root)
288
+ end
289
+
290
+ def trust_workspace_hooks!(workspace_root = Dir.pwd)
291
+ path = workspace_hooks_path(workspace_root)
292
+ raise "No workspace hook config found: #{path}" unless File.file?(path)
293
+
294
+ trusted = read_trusted_workspace_hooks
295
+ trusted[File.expand_path(path)] = workspace_hooks_digest(workspace_root)
296
+ PrivateFile.write_json(trusted_workspace_hooks_path, trusted)
297
+ end
298
+
299
+ def untrust_workspace_hooks!(workspace_root = Dir.pwd)
300
+ path = File.expand_path(workspace_hooks_path(workspace_root))
301
+ trusted = read_trusted_workspace_hooks
302
+ trusted.delete(path)
303
+ PrivateFile.write_json(trusted_workspace_hooks_path, trusted)
304
+ end
305
+
306
+ def workspace_hooks_digest(workspace_root = Dir.pwd)
307
+ Digest::SHA256.file(workspace_hooks_path(workspace_root)).hexdigest
308
+ end
309
+
310
+ def read_trusted_workspace_hooks
311
+ config = read_config(trusted_workspace_hooks_path)
312
+ config.is_a?(Hash) ? config : {}
313
+ rescue ConfigError
314
+ {}
315
+ end
316
+
317
+ def merge_hooks_config(config, workspace_config)
318
+ merged = JSON.parse(JSON.generate(config || {}))
319
+ merged["hooks"] = merge_hook_maps(merged["hooks"], workspace_config["hooks"] || workspace_config[:hooks])
320
+ merged
321
+ end
322
+
323
+ def merge_hook_maps(left, right)
324
+ left = left.is_a?(Hash) ? left : {}
325
+ right = right.is_a?(Hash) ? right : {}
326
+ merged = JSON.parse(JSON.generate(left))
327
+ right.each do |event, entries|
328
+ merged[event.to_s] = Array(merged[event.to_s]) + Array(entries)
329
+ end
330
+ merged
331
+ end
332
+
333
+ def read_kwsh_config
334
+ config = {
335
+ shell: Kwsh::DEFAULT_SHELL,
336
+ timeout_seconds: Kwsh::DEFAULT_TIMEOUT_SECONDS,
337
+ max_output_bytes: Kwsh::DEFAULT_MAX_OUTPUT_BYTES,
338
+ history_limit: Kwsh::DEFAULT_HISTORY_LIMIT,
339
+ env: {},
340
+ aliases: {}
341
+ }
342
+ rc_config = read_kwshrc_config
343
+ config[:env].merge!(rc_config[:env])
344
+ config[:aliases].merge!(rc_config[:aliases])
345
+ config
346
+ end
347
+
348
+ def read_kwshrc_config(paths = kwshrc_paths, env: ENV.to_h)
349
+ Kwshrc.read(paths, env: env)
350
+ rescue Kwshrc::ParseError => e
351
+ raise "Invalid kwshrc config: #{e.message}"
352
+ end
353
+
354
+ # Merges top-level config values and writes the updated config privately.
355
+ def update_config(values, path = config_path)
356
+ raise "Config values must be an object" unless values.is_a?(Hash)
357
+
358
+ config = read_config(path)
359
+ values.each { |key, value| config[key.to_s] = value }
360
+ write_config(config, path)
361
+ config
362
+ end
363
+
364
+ # Merges values into a one-level nested config section and writes privately.
365
+ def update_nested_config(section, values, path = config_path)
366
+ raise "Config values must be an object" unless values.is_a?(Hash)
367
+
368
+ config = read_config(path)
369
+ current = config[section.to_s].is_a?(Hash) ? config[section.to_s].dup : {}
370
+ config[section.to_s] = current.merge(values.transform_keys(&:to_s))
371
+ write_config(config, path)
372
+ config
373
+ end
374
+
375
+ # Removes a top-level config key when it exists.
376
+ def delete_config_key(key, path = config_path)
377
+ config = read_config(path)
378
+ existed = config.key?(key.to_s)
379
+ config.delete(key.to_s)
380
+ write_config(config, path) if existed
381
+ existed
382
+ end
383
+
384
+ # Returns the first present non-empty string value among several config keys.
385
+ def config_value(config, *keys)
386
+ keys.each do |key|
387
+ text = presence(config[key])
388
+ return text if text
389
+ end
390
+ nil
391
+ end
392
+
393
+ # Returns validated overlay settings with defaults for missing or invalid
394
+ # values.
395
+ #
396
+ # @param config [Hash] parsed config object
397
+ # @return [Hash] overlay settings with `alignment` and `width`
398
+ end
399
+ end
400
+ end
@@ -0,0 +1,99 @@
1
+ # Configuration extensions behavior.
2
+ module Kward
3
+ module ConfigFiles
4
+ module Extensions
5
+ extend self
6
+
7
+ # Lists configured skills discovered under the config directory.
8
+ #
9
+ # @return [Array<Skill>] skill metadata available to the model
10
+ def skills(workspace_root: Dir.pwd, warning_sink: nil, project_skill_paths: nil)
11
+ skills_registry(workspace_root: workspace_root, warning_sink: warning_sink, project_skill_paths: project_skill_paths).skills
12
+ end
13
+
14
+ def project_skill_candidates(workspace_root: Dir.pwd, warning_sink: nil)
15
+ return [] if ignore_local_instructions?
16
+
17
+ skills_registry(workspace_root: workspace_root, warning_sink: warning_sink).project_skill_candidates
18
+ end
19
+
20
+ # @return [String] trusted user plugin directory
21
+ def plugin_dir
22
+ File.expand_path("~/.kward/plugins")
23
+ end
24
+
25
+ # Finds trusted plugin files and package entrypoints.
26
+ #
27
+ # Plugins are intentionally loaded only from `~/.kward/plugins`, not from a
28
+ # workspace or custom `KWARD_CONFIG_PATH` directory.
29
+ #
30
+ # @return [Array<String>] sorted plugin file paths
31
+ def plugin_paths(warning_sink: nil)
32
+ plugins_root = plugin_dir
33
+ return [] unless Dir.exist?(plugins_root)
34
+
35
+ paths = Dir.glob(File.join(plugins_root, "*.rb"))
36
+ paths.concat(Dir.glob(File.join(plugins_root, "*", "plugin.rb")))
37
+ paths.sort
38
+ rescue StandardError => e
39
+ emit_warning("Warning: skipping Kward plugins in #{plugins_root}: #{e.message}", warning_sink: warning_sink)
40
+ []
41
+ end
42
+
43
+ # Lists prompt templates exposed as slash commands.
44
+ #
45
+ # @param reserved_commands [Array<String>] command names unavailable to templates
46
+ # @return [Array<PromptTemplate>] prompt template metadata and bodies
47
+ def prompt_templates(reserved_commands: [])
48
+ prompt_template_registry.prompt_templates(reserved_commands: reserved_commands)
49
+ end
50
+
51
+ # Reads a skill file by skill name and optional relative path.
52
+ #
53
+ # @param name [String] configured skill name
54
+ # @param relative_path [String, nil] path inside the skill directory
55
+ # @return [String] file contents or an error string
56
+ def read_skill_file(name, relative_path = nil, workspace_root: Dir.pwd)
57
+ skills_registry(workspace_root: workspace_root).read_skill_file(name, relative_path)
58
+ end
59
+
60
+ def skills_registry(workspace_root: Dir.pwd, warning_sink: nil, project_skill_paths: nil)
61
+ project_skill_paths = [] if ignore_local_instructions?
62
+ Skills::Registry.new(
63
+ config_dir: config_dir,
64
+ workspace_root: workspace_root,
65
+ project_skills_trusted: project_skills_trusted?,
66
+ skill_class: Skill,
67
+ max_file_bytes: MAX_SKILL_FILE_BYTES,
68
+ markdown_parser: ->(path) { Frontmatter.markdown_parts(path, lenient: true) },
69
+ inside_directory: method(:inside_directory?),
70
+ warning_sink: warning_sink || @warning_sink,
71
+ project_skill_paths: project_skill_paths
72
+ )
73
+ end
74
+
75
+ def prompt_template_registry
76
+ ::Kward::Prompts::Templates.new(
77
+ config_dir: config_dir,
78
+ template_class: PromptTemplate,
79
+ markdown_parser: ->(path) { Frontmatter.markdown_parts(path) },
80
+ warning_sink: @warning_sink
81
+ )
82
+ end
83
+
84
+ def emit_warning(message, warning_sink: nil)
85
+ sink = warning_sink || @warning_sink
86
+ sink ? sink.call(message) : warn(message)
87
+ end
88
+
89
+ def inside_directory?(path, base)
90
+ PathGuard.inside?(path, base)
91
+ end
92
+
93
+ def presence(value)
94
+ text = value.to_s
95
+ text.empty? ? nil : text
96
+ end
97
+ end
98
+ end
99
+ end
@@ -0,0 +1,11 @@
1
+ module Kward
2
+ # Shared user configuration location; resolving it does not load any config.
3
+ module ConfigPaths
4
+ def self.config_dir
5
+ path = ENV["KWARD_CONFIG_PATH"]
6
+ return File.expand_path(File.dirname(path)) if path && !path.empty?
7
+
8
+ File.expand_path("~/.kward")
9
+ end
10
+ end
11
+ end