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,93 @@
1
+ require_relative "../message_access"
2
+ require_relative "../terminal/text"
3
+
4
+ module Kward
5
+ # Shared plain-text presentation for terminal and exported turn summaries.
6
+ class TurnSummaryFormatter
7
+ def self.render(summary, mode: "compact", width: nil)
8
+ return "" unless summary.is_a?(Hash) && mode != "off"
9
+
10
+ new(summary).render(mode: mode, width: width)
11
+ end
12
+
13
+ def initialize(summary)
14
+ @summary = summary
15
+ end
16
+
17
+ def render(mode:, width:)
18
+ status = { "completed" => "Completed", "failed" => "Failed", "canceled" => "Cancelled" }.fetch(value(:status), "Finished")
19
+ parts = [status, format("%.1fs", value(:elapsedMs).to_f / 1_000), token_text]
20
+ parts << count_text(value(:modelRequests), "model request") if mode == "detailed"
21
+ parts << count_text(value(:toolCalls), "tool call")
22
+ lines = [fit(parts, width)]
23
+ if mode == "detailed" && usage.is_a?(Hash)
24
+ details = [
25
+ token_detail(:input_tokens, "Input"),
26
+ cached_detail,
27
+ token_detail(:output_tokens, "Output"),
28
+ token_detail(:reasoning_tokens, "Reasoning"),
29
+ token_detail(:cache_write_tokens, "Cache writes")
30
+ ].compact
31
+ lines << fit(details, width) unless details.empty?
32
+ end
33
+ lines.join("\n")
34
+ end
35
+
36
+ private
37
+
38
+ def value(key)
39
+ MessageAccess.value(@summary, key)
40
+ end
41
+
42
+ def usage
43
+ value(:usage)
44
+ end
45
+
46
+ def token_text
47
+ total = MessageAccess.value(usage, :total_tokens)
48
+ return "tokens unavailable" if value(:usageStatus) == "unavailable" || total.nil?
49
+
50
+ label = "#{number(total)} tokens"
51
+ label = "~#{label}" if MessageAccess.value(usage, :estimated)
52
+ label += " (partial)" if value(:usageStatus) == "partial"
53
+ label
54
+ end
55
+
56
+ def token_detail(field, label)
57
+ count = MessageAccess.value(usage, field)
58
+ return if count.nil?
59
+
60
+ text = "#{label} #{number(count)}"
61
+ partial_field?(field) ? "#{text} (partial)" : text
62
+ end
63
+
64
+ def partial_field?(field)
65
+ Array(MessageAccess.value(usage, :partial_fields)).include?(field.to_s)
66
+ end
67
+
68
+ def cached_detail
69
+ text = token_detail(:cache_read_tokens, "Cached")
70
+ return unless text
71
+
72
+ input = MessageAccess.value(usage, :input_tokens).to_f
73
+ cached = MessageAccess.value(usage, :cache_read_tokens).to_f
74
+ if value(:usageStatus) == "complete" && !partial_field?(:input_tokens) && !partial_field?(:cache_read_tokens) && input.positive? && cached <= input
75
+ text += format(" (%.0f%%)", 100 * cached / input)
76
+ end
77
+ text
78
+ end
79
+
80
+ def number(value)
81
+ value.to_f >= 1_000 ? format("%.1fk", value.to_f / 1_000) : value.to_i.to_s
82
+ end
83
+
84
+ def count_text(count, noun)
85
+ "#{count.to_i} #{noun}#{count.to_i == 1 ? '' : 's'}"
86
+ end
87
+
88
+ def fit(parts, width)
89
+ parts.pop while width && parts.length > 1 && TerminalText.width(parts.join(" · ")) > width
90
+ parts.join(" · ")
91
+ end
92
+ end
93
+ end
@@ -0,0 +1,200 @@
1
+ # Frontend-neutral external transport contracts.
2
+ require "logger"
3
+ require_relative "../deep_copy"
4
+
5
+ # Namespace for frontend-neutral external transport contracts.
6
+ module Kward
7
+ module Transport
8
+ STREAMING_MODES = %i[native edit aggregate none].freeze
9
+
10
+ Actor = Data.define(:id, :display_name, :metadata)
11
+ Attachment = Data.define(:name, :mime_type, :data, :url, :metadata)
12
+ ConversationKey = Data.define(:transport_id, :external_id)
13
+ InboundMessage = Data.define(
14
+ :conversation,
15
+ :message_id,
16
+ :actor,
17
+ :text,
18
+ :attachments,
19
+ :reply_context,
20
+ :idempotency_key,
21
+ :metadata
22
+ )
23
+ TurnEvent = Data.define(:type, :session_id, :turn_id, :sequence, :payload)
24
+ InteractionRequest = Data.define(
25
+ :id,
26
+ :session_id,
27
+ :turn_id,
28
+ :kind,
29
+ :prompt,
30
+ :choices,
31
+ :expires_at,
32
+ :metadata
33
+ )
34
+ Capabilities = Data.define(:inbound, :outbound, :streaming, :limits)
35
+ ExecutionProfile = Data.define(
36
+ :id,
37
+ :tool_mode,
38
+ :allowed_tools,
39
+ :disabled_tools,
40
+ :plugin_commands,
41
+ :approval_mode,
42
+ :memory,
43
+ :attachments,
44
+ :workspace_mode,
45
+ :prompt_context
46
+ )
47
+
48
+ TOOL_MODES = %i[all none allowlist].freeze
49
+ APPROVAL_MODES = %i[default ask deny].freeze
50
+ MEMORY_MODES = %i[default none].freeze
51
+ WORKSPACE_MODES = %i[session fixed].freeze
52
+
53
+ module_function
54
+
55
+ def actor(id:, display_name: nil, metadata: {})
56
+ Actor.new(
57
+ id: required_string(id, "actor id"),
58
+ display_name: optional_string(display_name),
59
+ metadata: frozen_copy(metadata)
60
+ )
61
+ end
62
+
63
+ def attachment(name: nil, mime_type:, data: nil, url: nil, metadata: {})
64
+ raise ArgumentError, "attachment requires data or url" if data.nil? && url.nil?
65
+ raise ArgumentError, "attachment cannot contain both data and url" unless data.nil? || url.nil?
66
+
67
+ Attachment.new(
68
+ name: optional_string(name),
69
+ mime_type: required_string(mime_type, "attachment MIME type"),
70
+ data: data&.dup&.freeze,
71
+ url: url && required_string(url, "attachment URL"),
72
+ metadata: frozen_copy(metadata)
73
+ )
74
+ end
75
+
76
+ def conversation_key(transport_id:, external_id:)
77
+ ConversationKey.new(
78
+ transport_id: required_string(transport_id, "transport id"),
79
+ external_id: required_string(external_id, "external conversation id")
80
+ )
81
+ end
82
+
83
+ def inbound_message(conversation:, message_id:, actor:, text: "", attachments: [], reply_context: {}, idempotency_key:, metadata: {})
84
+ unless conversation.is_a?(ConversationKey)
85
+ raise ArgumentError, "conversation must be a Transport::ConversationKey"
86
+ end
87
+ unless actor.is_a?(Actor)
88
+ raise ArgumentError, "actor must be a Transport::Actor"
89
+ end
90
+
91
+ InboundMessage.new(
92
+ conversation: conversation,
93
+ message_id: required_string(message_id, "message id"),
94
+ actor: actor,
95
+ text: text.to_s.freeze,
96
+ attachments: frozen_copy(Array(attachments)),
97
+ reply_context: frozen_copy(reply_context),
98
+ idempotency_key: required_string(idempotency_key, "idempotency key"),
99
+ metadata: frozen_copy(metadata)
100
+ )
101
+ end
102
+
103
+ def turn_event(type:, session_id:, turn_id:, sequence:, payload: {})
104
+ TurnEvent.new(
105
+ type: required_string(type, "turn event type"),
106
+ session_id: required_string(session_id, "session id"),
107
+ turn_id: required_string(turn_id, "turn id"),
108
+ sequence: Integer(sequence),
109
+ payload: frozen_copy(payload)
110
+ )
111
+ end
112
+
113
+ def interaction_request(id:, session_id:, turn_id:, kind:, prompt:, choices: [], expires_at: nil, metadata: {})
114
+ InteractionRequest.new(
115
+ id: required_string(id, "interaction id"),
116
+ session_id: required_string(session_id, "session id"),
117
+ turn_id: required_string(turn_id, "turn id"),
118
+ kind: required_string(kind, "interaction kind"),
119
+ prompt: required_string(prompt, "interaction prompt"),
120
+ choices: frozen_copy(Array(choices)),
121
+ expires_at: expires_at,
122
+ metadata: frozen_copy(metadata)
123
+ )
124
+ end
125
+
126
+ def execution_profile(
127
+ id:,
128
+ tool_mode: :all,
129
+ allowed_tools: nil,
130
+ disabled_tools: nil,
131
+ plugin_commands: true,
132
+ approval_mode: :default,
133
+ memory: :default,
134
+ attachments: true,
135
+ workspace_mode: :session,
136
+ prompt_context: nil
137
+ )
138
+ id = required_string(id, "execution profile id")
139
+ tool_mode = tool_mode.to_sym
140
+ approval_mode = approval_mode.to_sym
141
+ memory = memory.to_sym
142
+ workspace_mode = workspace_mode.to_sym
143
+ raise ArgumentError, "unsupported tool mode: #{tool_mode}" unless TOOL_MODES.include?(tool_mode)
144
+ raise ArgumentError, "unsupported approval mode: #{approval_mode}" unless APPROVAL_MODES.include?(approval_mode)
145
+ raise ArgumentError, "unsupported memory mode: #{memory}" unless MEMORY_MODES.include?(memory)
146
+ raise ArgumentError, "unsupported workspace mode: #{workspace_mode}" unless WORKSPACE_MODES.include?(workspace_mode)
147
+ raise ArgumentError, "allowlist tool mode requires allowed_tools" if tool_mode == :allowlist && Array(allowed_tools).empty?
148
+ raise ArgumentError, "none tool mode cannot define allowed_tools" if tool_mode == :none && allowed_tools
149
+ raise ArgumentError, "allowed_tools and disabled_tools cannot both be set" if allowed_tools && disabled_tools
150
+
151
+ ExecutionProfile.new(
152
+ id: id,
153
+ tool_mode: tool_mode,
154
+ allowed_tools: frozen_symbols(allowed_tools),
155
+ disabled_tools: frozen_symbols(disabled_tools),
156
+ plugin_commands: !!plugin_commands,
157
+ approval_mode: approval_mode,
158
+ memory: memory,
159
+ attachments: !!attachments,
160
+ workspace_mode: workspace_mode,
161
+ prompt_context: prompt_context.nil? ? nil : prompt_context.to_s.freeze
162
+ )
163
+ end
164
+
165
+ def capabilities(inbound: [], outbound: [], streaming: :none, limits: {})
166
+ streaming = streaming.to_sym
167
+ raise ArgumentError, "unsupported streaming mode: #{streaming}" unless STREAMING_MODES.include?(streaming)
168
+
169
+ Capabilities.new(
170
+ inbound: frozen_symbols(inbound),
171
+ outbound: frozen_symbols(outbound),
172
+ streaming: streaming,
173
+ limits: frozen_copy(limits)
174
+ )
175
+ end
176
+
177
+ def required_string(value, name)
178
+ value = value.to_s
179
+ raise ArgumentError, "#{name} is required" if value.empty?
180
+
181
+ value.freeze
182
+ end
183
+ private_class_method :required_string
184
+
185
+ def optional_string(value)
186
+ value.nil? ? nil : value.to_s.freeze
187
+ end
188
+ private_class_method :optional_string
189
+
190
+ def frozen_symbols(values)
191
+ Array(values).map { |value| value.to_sym }.uniq.freeze
192
+ end
193
+ private_class_method :frozen_symbols
194
+
195
+ def frozen_copy(value)
196
+ DeepCopy.freeze(DeepCopy.dup(value))
197
+ end
198
+ private_class_method :frozen_copy
199
+ end
200
+ end
@@ -13,6 +13,7 @@ module Kward
13
13
  # without changing transport plugins.
14
14
  class Gateway
15
15
  POLL_INTERVAL = 0.05
16
+ INTERACTION_ROUTE_LIMIT = 1_000
16
17
  TERMINAL_STATUSES = %w[completed canceled failed].freeze
17
18
 
18
19
  def initialize(session_manager:, transport_id:, storage: nil, poll_interval: POLL_INTERVAL)
@@ -22,6 +23,7 @@ module Kward
22
23
  @poll_interval = poll_interval
23
24
  @subscriptions = []
24
25
  @interaction_subscribers = []
26
+ @interaction_routes = {}
25
27
  @mutex = Mutex.new
26
28
  @session_manager.subscribe_events { |method, payload| handle_runtime_event(method, payload) } if @session_manager.respond_to?(:subscribe_events)
27
29
  end
@@ -50,7 +52,8 @@ module Kward
50
52
  attachments: normalize_attachments(attachments, execution_profile: execution_profile),
51
53
  options: profile_options(options, execution_profile),
52
54
  streaming_behavior: streaming_behavior,
53
- execution_profile: execution_profile
55
+ execution_profile: execution_profile,
56
+ image_previews: false
54
57
  )
55
58
  { id: payload.fetch(:id), session_id: payload.fetch(:sessionId) }
56
59
  end
@@ -73,19 +76,16 @@ module Kward
73
76
  end
74
77
 
75
78
  def answer_transport_interaction(session_id:, request_id:, answer:)
76
- if answer == true || answer == false
77
- @session_manager.answer_tool_approval(
78
- session_id: session_id,
79
- approval_request_id: request_id,
80
- approved: answer
81
- )
79
+ route = @mutex.synchronize { @interaction_routes.delete(request_id.to_s) }
80
+ case route
81
+ when :plugin_ui
82
+ @session_manager.answer_plugin_ui(session_id: session_id, request_id: request_id, value: answer)
83
+ when :tool_approval
84
+ @session_manager.answer_tool_approval(session_id: session_id, approval_request_id: request_id, approved: answer == true)
85
+ when :question
86
+ answer_transport_question(session_id, request_id, answer)
82
87
  else
83
- answers = answer.is_a?(Array) ? answer : [{ question: request_id, answer: answer.to_s }]
84
- @session_manager.answer_question(
85
- session_id: session_id,
86
- question_request_id: request_id,
87
- answers: answers
88
- )
88
+ answer == true || answer == false ? answer_transport_approval(session_id, request_id, answer) : answer_transport_question(session_id, request_id, answer)
89
89
  end
90
90
  end
91
91
 
@@ -122,6 +122,7 @@ module Kward
122
122
  current = @subscriptions
123
123
  @subscriptions = []
124
124
  @interaction_subscribers = []
125
+ @interaction_routes = {}
125
126
  current
126
127
  end
127
128
  subscriptions.each(&:kill)
@@ -168,31 +169,17 @@ module Kward
168
169
  end
169
170
 
170
171
  def handle_runtime_event(method, payload)
171
- request = case method
172
- when "ui/question"
173
- questions = Array(payload[:questions] || payload["questions"])
174
- Transport.interaction_request(
175
- id: payload[:questionRequestId] || payload["questionRequestId"],
176
- session_id: payload[:sessionId] || payload["sessionId"],
177
- turn_id: payload[:turnId] || payload["turnId"] || "unknown",
178
- kind: :question,
179
- prompt: questions.map { |question| question[:question] || question["question"] }.join("\\n"),
180
- choices: questions
181
- )
182
- when "tool/approvalRequested"
183
- Transport.interaction_request(
184
- id: payload[:approvalRequestId] || payload["approvalRequestId"],
185
- session_id: payload[:sessionId] || payload["sessionId"],
186
- turn_id: payload[:turnId] || payload["turnId"] || "unknown",
187
- kind: :tool_approval,
188
- prompt: "Allow #{payload[:toolName] || payload["toolName"]}?",
189
- choices: [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
190
- metadata: { tool_call_id: payload[:toolCallId] || payload["toolCallId"], args: payload[:args] || payload["args"] }
191
- )
192
- end
172
+ request, route = interaction_for_runtime_event(method, payload)
193
173
  return unless request
194
174
 
195
- subscribers = @mutex.synchronize { @interaction_subscribers.dup }
175
+ subscribers = @mutex.synchronize do
176
+ current = @interaction_subscribers.dup
177
+ if route && !current.empty?
178
+ @interaction_routes[request.id.to_s] = route
179
+ @interaction_routes.shift while @interaction_routes.length > INTERACTION_ROUTE_LIMIT
180
+ end
181
+ current
182
+ end
196
183
  subscribers.each do |subscriber|
197
184
  begin
198
185
  subscriber.call(request)
@@ -202,6 +189,64 @@ module Kward
202
189
  end
203
190
  end
204
191
 
192
+ def interaction_for_runtime_event(method, payload)
193
+ session_id = payload[:sessionId] || payload["sessionId"]
194
+ turn_id = payload[:turnId] || payload["turnId"] || "unknown"
195
+ case method
196
+ when "ui/question"
197
+ questions = Array(payload[:questions] || payload["questions"])
198
+ [Transport.interaction_request(
199
+ id: payload[:questionRequestId] || payload["questionRequestId"],
200
+ session_id: session_id,
201
+ turn_id: turn_id,
202
+ kind: :question,
203
+ prompt: questions.map { |question| question[:question] || question["question"] }.join("\\n"),
204
+ choices: questions
205
+ ), :question]
206
+ when "ui/request"
207
+ plugin_ui_interaction(payload, session_id, turn_id)
208
+ when "tool/approvalRequested"
209
+ [Transport.interaction_request(
210
+ id: payload[:approvalRequestId] || payload["approvalRequestId"],
211
+ session_id: session_id,
212
+ turn_id: turn_id,
213
+ kind: :tool_approval,
214
+ prompt: "Allow #{payload[:toolName] || payload["toolName"]}?",
215
+ choices: [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
216
+ metadata: { tool_call_id: payload[:toolCallId] || payload["toolCallId"], args: payload[:args] || payload["args"] }
217
+ ), :tool_approval]
218
+ end
219
+ end
220
+
221
+ def plugin_ui_interaction(payload, session_id, turn_id)
222
+ kind = (payload[:kind] || payload["kind"]).to_s
223
+ details = payload[:payload] || payload["payload"] || {}
224
+ prompt = details[:message] || details["message"] || details[:title] || details["title"]
225
+ choices = details[:options] || details["options"] || []
226
+ if kind == "confirm"
227
+ choices = [{ label: "Yes", value: true }, { label: "No", value: false }]
228
+ end
229
+ default = details.key?(:default) ? details[:default] : details["default"]
230
+ [Transport.interaction_request(
231
+ id: payload[:requestId] || payload["requestId"],
232
+ session_id: session_id,
233
+ turn_id: turn_id,
234
+ kind: kind,
235
+ prompt: prompt,
236
+ choices: choices,
237
+ metadata: { title: details[:title] || details["title"], placeholder: details[:placeholder] || details["placeholder"], default: default }.compact
238
+ ), :plugin_ui]
239
+ end
240
+
241
+ def answer_transport_approval(session_id, request_id, answer)
242
+ @session_manager.answer_tool_approval(session_id: session_id, approval_request_id: request_id, approved: answer)
243
+ end
244
+
245
+ def answer_transport_question(session_id, request_id, answer)
246
+ answers = answer.is_a?(Array) ? answer : [{ question: request_id, answer: answer.to_s }]
247
+ @session_manager.answer_question(session_id: session_id, question_request_id: request_id, answers: answers)
248
+ end
249
+
205
250
  def profile_options(options, profile)
206
251
  return options unless profile
207
252
 
@@ -1,6 +1,6 @@
1
1
  require "base64"
2
2
  require "thread"
3
- require_relative "../plugin_chat_runtime"
3
+ require_relative "../plugins/chat_runtime"
4
4
 
5
5
  module Kward
6
6
  module Transport
@@ -45,9 +45,10 @@ module Kward
45
45
  raise ArgumentError, "plugin chat turns do not support #{streaming_behavior} streaming"
46
46
  end
47
47
 
48
+ chat = fetch_chat(chat_id)
48
49
  turn = @runtime.start_turn(
49
50
  chat_id: chat_id,
50
- input: @runtime.input_with_attachments(input, normalize_attachments(attachments)),
51
+ input: @runtime.input_with_attachments(input, normalize_attachments(attachments), capabilities: chat.type.capabilities),
51
52
  display_input: input.to_s,
52
53
  context: { actor: actor }
53
54
  )
@@ -1,203 +1,4 @@
1
- require "logger"
2
- require_relative "deep_copy"
3
-
4
- # Namespace for frontend-neutral external transport contracts.
5
- module Kward
6
- module Transport
7
- STREAMING_MODES = %i[native edit aggregate none].freeze
8
-
9
- Actor = Data.define(:id, :display_name, :metadata)
10
- Attachment = Data.define(:name, :mime_type, :data, :url, :metadata)
11
- ConversationKey = Data.define(:transport_id, :external_id)
12
- InboundMessage = Data.define(
13
- :conversation,
14
- :message_id,
15
- :actor,
16
- :text,
17
- :attachments,
18
- :reply_context,
19
- :idempotency_key,
20
- :metadata
21
- )
22
- TurnEvent = Data.define(:type, :session_id, :turn_id, :sequence, :payload)
23
- InteractionRequest = Data.define(
24
- :id,
25
- :session_id,
26
- :turn_id,
27
- :kind,
28
- :prompt,
29
- :choices,
30
- :expires_at,
31
- :metadata
32
- )
33
- Capabilities = Data.define(:inbound, :outbound, :streaming, :limits)
34
- ExecutionProfile = Data.define(
35
- :id,
36
- :tool_mode,
37
- :allowed_tools,
38
- :disabled_tools,
39
- :plugin_commands,
40
- :approval_mode,
41
- :memory,
42
- :attachments,
43
- :workspace_mode,
44
- :prompt_context
45
- )
46
-
47
- TOOL_MODES = %i[all none allowlist].freeze
48
- APPROVAL_MODES = %i[default ask deny].freeze
49
- MEMORY_MODES = %i[default none].freeze
50
- WORKSPACE_MODES = %i[session fixed].freeze
51
-
52
- module_function
53
-
54
- def actor(id:, display_name: nil, metadata: {})
55
- Actor.new(
56
- id: required_string(id, "actor id"),
57
- display_name: optional_string(display_name),
58
- metadata: frozen_copy(metadata)
59
- )
60
- end
61
-
62
- def attachment(name: nil, mime_type:, data: nil, url: nil, metadata: {})
63
- raise ArgumentError, "attachment requires data or url" if data.nil? && url.nil?
64
- raise ArgumentError, "attachment cannot contain both data and url" unless data.nil? || url.nil?
65
-
66
- Attachment.new(
67
- name: optional_string(name),
68
- mime_type: required_string(mime_type, "attachment MIME type"),
69
- data: data&.dup&.freeze,
70
- url: url && required_string(url, "attachment URL"),
71
- metadata: frozen_copy(metadata)
72
- )
73
- end
74
-
75
- def conversation_key(transport_id:, external_id:)
76
- ConversationKey.new(
77
- transport_id: required_string(transport_id, "transport id"),
78
- external_id: required_string(external_id, "external conversation id")
79
- )
80
- end
81
-
82
- def inbound_message(conversation:, message_id:, actor:, text: "", attachments: [], reply_context: {}, idempotency_key:, metadata: {})
83
- unless conversation.is_a?(ConversationKey)
84
- raise ArgumentError, "conversation must be a Transport::ConversationKey"
85
- end
86
- unless actor.is_a?(Actor)
87
- raise ArgumentError, "actor must be a Transport::Actor"
88
- end
89
-
90
- InboundMessage.new(
91
- conversation: conversation,
92
- message_id: required_string(message_id, "message id"),
93
- actor: actor,
94
- text: text.to_s.freeze,
95
- attachments: frozen_copy(Array(attachments)),
96
- reply_context: frozen_copy(reply_context),
97
- idempotency_key: required_string(idempotency_key, "idempotency key"),
98
- metadata: frozen_copy(metadata)
99
- )
100
- end
101
-
102
- def turn_event(type:, session_id:, turn_id:, sequence:, payload: {})
103
- TurnEvent.new(
104
- type: required_string(type, "turn event type"),
105
- session_id: required_string(session_id, "session id"),
106
- turn_id: required_string(turn_id, "turn id"),
107
- sequence: Integer(sequence),
108
- payload: frozen_copy(payload)
109
- )
110
- end
111
-
112
- def interaction_request(id:, session_id:, turn_id:, kind:, prompt:, choices: [], expires_at: nil, metadata: {})
113
- InteractionRequest.new(
114
- id: required_string(id, "interaction id"),
115
- session_id: required_string(session_id, "session id"),
116
- turn_id: required_string(turn_id, "turn id"),
117
- kind: required_string(kind, "interaction kind"),
118
- prompt: required_string(prompt, "interaction prompt"),
119
- choices: frozen_copy(Array(choices)),
120
- expires_at: expires_at,
121
- metadata: frozen_copy(metadata)
122
- )
123
- end
124
-
125
- def execution_profile(
126
- id:,
127
- tool_mode: :all,
128
- allowed_tools: nil,
129
- disabled_tools: nil,
130
- plugin_commands: true,
131
- approval_mode: :default,
132
- memory: :default,
133
- attachments: true,
134
- workspace_mode: :session,
135
- prompt_context: nil
136
- )
137
- id = required_string(id, "execution profile id")
138
- tool_mode = tool_mode.to_sym
139
- approval_mode = approval_mode.to_sym
140
- memory = memory.to_sym
141
- workspace_mode = workspace_mode.to_sym
142
- raise ArgumentError, "unsupported tool mode: #{tool_mode}" unless TOOL_MODES.include?(tool_mode)
143
- raise ArgumentError, "unsupported approval mode: #{approval_mode}" unless APPROVAL_MODES.include?(approval_mode)
144
- raise ArgumentError, "unsupported memory mode: #{memory}" unless MEMORY_MODES.include?(memory)
145
- raise ArgumentError, "unsupported workspace mode: #{workspace_mode}" unless WORKSPACE_MODES.include?(workspace_mode)
146
- raise ArgumentError, "allowlist tool mode requires allowed_tools" if tool_mode == :allowlist && Array(allowed_tools).empty?
147
- raise ArgumentError, "none tool mode cannot define allowed_tools" if tool_mode == :none && allowed_tools
148
- raise ArgumentError, "allowed_tools and disabled_tools cannot both be set" if allowed_tools && disabled_tools
149
-
150
- ExecutionProfile.new(
151
- id: id,
152
- tool_mode: tool_mode,
153
- allowed_tools: frozen_symbols(allowed_tools),
154
- disabled_tools: frozen_symbols(disabled_tools),
155
- plugin_commands: !!plugin_commands,
156
- approval_mode: approval_mode,
157
- memory: memory,
158
- attachments: !!attachments,
159
- workspace_mode: workspace_mode,
160
- prompt_context: prompt_context.nil? ? nil : prompt_context.to_s.freeze
161
- )
162
- end
163
-
164
- def capabilities(inbound: [], outbound: [], streaming: :none, limits: {})
165
- streaming = streaming.to_sym
166
- raise ArgumentError, "unsupported streaming mode: #{streaming}" unless STREAMING_MODES.include?(streaming)
167
-
168
- Capabilities.new(
169
- inbound: frozen_symbols(inbound),
170
- outbound: frozen_symbols(outbound),
171
- streaming: streaming,
172
- limits: frozen_copy(limits)
173
- )
174
- end
175
-
176
- def required_string(value, name)
177
- value = value.to_s
178
- raise ArgumentError, "#{name} is required" if value.empty?
179
-
180
- value.freeze
181
- end
182
- private_class_method :required_string
183
-
184
- def optional_string(value)
185
- value.nil? ? nil : value.to_s.freeze
186
- end
187
- private_class_method :optional_string
188
-
189
- def frozen_symbols(values)
190
- Array(values).map { |value| value.to_sym }.uniq.freeze
191
- end
192
- private_class_method :frozen_symbols
193
-
194
- def frozen_copy(value)
195
- DeepCopy.freeze(DeepCopy.dup(value))
196
- end
197
- private_class_method :frozen_copy
198
- end
199
- end
200
-
1
+ require_relative "transport/contracts"
201
2
  require_relative "transport/store"
202
3
  require_relative "transport/host"
203
4
  require_relative "transport/manager"