kward 0.85.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 (151) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +130 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +3 -3
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +11 -0
  8. data/doc/api.md +4 -1
  9. data/doc/composer.md +4 -3
  10. data/doc/configuration.md +60 -11
  11. data/doc/extensibility.md +2 -0
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +1 -1
  14. data/doc/memory.md +1 -1
  15. data/doc/plugins.md +40 -5
  16. data/doc/providers.md +10 -4
  17. data/doc/rpc.md +125 -7
  18. data/doc/session-management.md +36 -1
  19. data/doc/shell.md +643 -27
  20. data/doc/tabs.md +2 -1
  21. data/doc/troubleshooting.md +1 -1
  22. data/doc/usage.md +21 -11
  23. data/examples/plugins/openrouter_proxy/README.md +103 -0
  24. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  25. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  26. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  27. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  28. data/examples/plugins/space_invaders.rb +0 -1
  29. data/exe/kward +2 -2
  30. data/exe/kwsh +7 -0
  31. data/kward.gemspec +3 -1
  32. data/lib/kward/agent.rb +43 -9
  33. data/lib/kward/cli/commands.rb +41 -11
  34. data/lib/kward/cli/interactive_turn.rb +10 -0
  35. data/lib/kward/cli/plugins.rb +5 -1
  36. data/lib/kward/cli/prompt_interface.rb +4 -1
  37. data/lib/kward/cli/rendering.rb +21 -28
  38. data/lib/kward/cli/runtime_helpers.rb +52 -34
  39. data/lib/kward/cli/settings/model.rb +1 -12
  40. data/lib/kward/cli/tabs.rb +91 -18
  41. data/lib/kward/cli/tool_summaries.rb +2 -0
  42. data/lib/kward/cli/transcript_formatter.rb +3 -10
  43. data/lib/kward/cli/worktrees.rb +1 -0
  44. data/lib/kward/cli.rb +56 -7
  45. data/lib/kward/config/core.rb +16 -5
  46. data/lib/kward/config/extensions.rb +3 -0
  47. data/lib/kward/config/paths.rb +11 -0
  48. data/lib/kward/config/settings.rb +7 -0
  49. data/lib/kward/conversation.rb +11 -1
  50. data/lib/kward/entrypoint.rb +14 -0
  51. data/lib/kward/events.rb +2 -0
  52. data/lib/kward/generated_images.rb +237 -0
  53. data/lib/kward/model/catalog.rb +6 -3
  54. data/lib/kward/model/client.rb +105 -36
  55. data/lib/kward/model/codex_images.rb +83 -0
  56. data/lib/kward/model/copilot_models.rb +8 -4
  57. data/lib/kward/model/model_info.rb +27 -9
  58. data/lib/kward/model/openrouter_model_cache.rb +4 -2
  59. data/lib/kward/model/payloads.rb +6 -5
  60. data/lib/kward/model/sources.rb +3 -1
  61. data/lib/kward/model/stream_parser.rb +4 -7
  62. data/lib/kward/pan/index.html.erb +8 -1
  63. data/lib/kward/pan/server.rb +13 -1
  64. data/lib/kward/plugins/codex_responses.rb +73 -0
  65. data/lib/kward/plugins/host.rb +16 -0
  66. data/lib/kward/plugins/http_server.rb +83 -0
  67. data/lib/kward/plugins/registry.rb +39 -0
  68. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  69. data/lib/kward/prompt_interface/composer_renderer.rb +159 -72
  70. data/lib/kward/prompt_interface/editor/controller.rb +1 -1
  71. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  72. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  73. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  74. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  75. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  76. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  77. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  78. data/lib/kward/prompt_interface/layout.rb +11 -1
  79. data/lib/kward/prompt_interface/overlay_renderer.rb +25 -8
  80. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  81. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  82. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  83. data/lib/kward/prompt_interface/runtime_state.rb +31 -9
  84. data/lib/kward/prompt_interface/screen.rb +24 -21
  85. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  86. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  87. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  88. data/lib/kward/prompt_interface.rb +109 -39
  89. data/lib/kward/prompts.rb +7 -1
  90. data/lib/kward/pty/adaptive_output_sink.rb +38 -4
  91. data/lib/kward/pty/interactive_runner.rb +20 -28
  92. data/lib/kward/pty/transcript_normalizer.rb +65 -21
  93. data/lib/kward/rpc/config_manager.rb +3 -0
  94. data/lib/kward/rpc/server.rb +27 -5
  95. data/lib/kward/rpc/session_manager.rb +62 -17
  96. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  97. data/lib/kward/sessions/store.rb +30 -3
  98. data/lib/kward/shell/kwsh.rb +27 -7
  99. data/lib/kward/shell/kwshrc.rb +11 -2
  100. data/lib/kward/shell/native_arithmetic.rb +255 -0
  101. data/lib/kward/shell/native_arrays.rb +102 -0
  102. data/lib/kward/shell/native_braces.rb +96 -0
  103. data/lib/kward/shell/native_builtins.rb +476 -0
  104. data/lib/kward/shell/native_completion.rb +169 -0
  105. data/lib/kward/shell/native_condition.rb +75 -0
  106. data/lib/kward/shell/native_directory.rb +116 -0
  107. data/lib/kward/shell/native_exec_state.rb +73 -0
  108. data/lib/kward/shell/native_expansion.rb +252 -0
  109. data/lib/kward/shell/native_fields.rb +62 -0
  110. data/lib/kward/shell/native_glob.rb +96 -0
  111. data/lib/kward/shell/native_history.rb +242 -0
  112. data/lib/kward/shell/native_interactive.rb +164 -0
  113. data/lib/kward/shell/native_invocation.rb +42 -0
  114. data/lib/kward/shell/native_jobs.rb +250 -0
  115. data/lib/kward/shell/native_line_editor.rb +382 -0
  116. data/lib/kward/shell/native_line_terminal.rb +286 -0
  117. data/lib/kward/shell/native_locale.rb +109 -0
  118. data/lib/kward/shell/native_locals.rb +57 -0
  119. data/lib/kward/shell/native_pattern.rb +200 -0
  120. data/lib/kward/shell/native_process.rb +279 -0
  121. data/lib/kward/shell/native_program.rb +40 -0
  122. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  123. data/lib/kward/shell/native_prompt_format.rb +89 -0
  124. data/lib/kward/shell/native_runtime.rb +964 -0
  125. data/lib/kward/shell/native_substitution.rb +110 -0
  126. data/lib/kward/shell/native_syntax.rb +946 -0
  127. data/lib/kward/shell/native_traps.rb +196 -0
  128. data/lib/kward/shell/native_vi.rb +407 -0
  129. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  130. data/lib/kward/shell/native_worker.rb +82 -0
  131. data/lib/kward/shell/persistent_session.rb +184 -190
  132. data/lib/kward/shell/prompt.rb +14 -0
  133. data/lib/kward/shell/prompt_agent.rb +17 -0
  134. data/lib/kward/shell/script_runner.rb +244 -0
  135. data/lib/kward/shell/standalone_agent.rb +31 -0
  136. data/lib/kward/shell/standalone_link.rb +78 -0
  137. data/lib/kward/shell/standalone_terminal.rb +287 -0
  138. data/lib/kward/terminal/keys.rb +22 -1
  139. data/lib/kward/terminal/locale_text.rb +29 -0
  140. data/lib/kward/terminal/sequences.rb +45 -4
  141. data/lib/kward/tools/datetime.rb +85 -0
  142. data/lib/kward/tools/generate_image.rb +36 -0
  143. data/lib/kward/tools/registry.rb +35 -9
  144. data/lib/kward/tools/tool_call.rb +3 -1
  145. data/lib/kward/transcripts/markdown_transcript.rb +8 -0
  146. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  147. data/lib/kward/transport/gateway.rb +2 -1
  148. data/lib/kward/turn_summary.rb +68 -0
  149. data/lib/kward/version.rb +1 -1
  150. data/lib/main.rb +6 -3
  151. metadata +84 -1
@@ -0,0 +1,186 @@
1
+ require "json"
2
+ require "thread"
3
+ require_relative "protocol"
4
+ require_relative "fake_embeddings"
5
+
6
+ module Kward
7
+ module OpenRouterProxy
8
+ class Server
9
+ ENDPOINT_PATH = "/api/v1/chat/completions"
10
+ EMBEDDINGS_ENDPOINT_PATH = "/api/v1/embeddings"
11
+ DEFAULT_PORT = 4000
12
+ DEFAULT_MAX_BODY_BYTES = 1_048_576
13
+ MAX_NONSTREAM_EVENTS = 100_000
14
+
15
+ def initialize(host:, codex: host.codex_responses, output: $stderr)
16
+ @host = host
17
+ @codex = codex
18
+ @output = output
19
+ @config = host.config
20
+ model_map = @config.fetch("model_map", {})
21
+ raise ArgumentError, "Configure at least one proxy model mapping" unless model_map.is_a?(Hash) && !model_map.empty?
22
+
23
+ @protocol = Protocol.new(model_map: model_map)
24
+ @fake_embeddings = FakeEmbeddings.new(models: @config.fetch("fake_embedding_models", {}))
25
+ @api_key = host.secret("api_key")
26
+ raise ArgumentError, "Configure the proxy api_key secret before starting" if @api_key.to_s.empty?
27
+ end
28
+
29
+ def run
30
+ listener = @host.http_server(
31
+ host: "127.0.0.1",
32
+ port: integer_config("port", DEFAULT_PORT, min: 0, max: 65_535),
33
+ max_body_bytes: integer_config("max_body_bytes", DEFAULT_MAX_BODY_BYTES, min: 1024, max: 16_777_216)
34
+ ) { |request, response| handle(request, response) }
35
+ listener.start
36
+ @output.puts("OpenRouter-compatible proxy listening at http://127.0.0.1:#{listener.port}/api/v1")
37
+ listener.wait
38
+ ensure
39
+ listener&.stop
40
+ end
41
+
42
+ def handle(request, response)
43
+ return unauthorized(response) unless authorized?(request)
44
+ unless [ENDPOINT_PATH, EMBEDDINGS_ENDPOINT_PATH].include?(request.path)
45
+ return write_error(response, 404, "Not found", "not_found")
46
+ end
47
+ return write_error(response, 405, "Method not allowed", "method_not_allowed") unless request.request_method == "POST"
48
+ return write_error(response, 415, "Content-Type must be application/json", "invalid_content_type") unless request["content-type"].to_s.downcase.start_with?("application/json")
49
+
50
+ payload = JSON.parse(request.body.to_s)
51
+ return write_json(response, 200, @fake_embeddings.create(payload)) if request.path == EMBEDDINGS_ENDPOINT_PATH
52
+
53
+ parsed = @protocol.parse_request(payload)
54
+ parsed.stream ? handle_stream(parsed, response) : handle_nonstream(parsed, response)
55
+ rescue JSON::ParserError
56
+ write_error(response, 400, "Invalid JSON request body", "invalid_json")
57
+ rescue RequestError => error
58
+ write_error(response, error.status, error.message, error.status >= 500 ? "upstream_error" : "invalid_request")
59
+ rescue PluginCodexResponses::AuthenticationError
60
+ write_error(response, 503, "Kward Codex authentication is unavailable", "upstream_authentication_error")
61
+ rescue PluginCodexResponses::RequestError => error
62
+ write_error(response, 502, error.message, "upstream_error")
63
+ rescue Cancellation::CancelledError
64
+ nil
65
+ rescue StandardError
66
+ write_error(response, 502, "Codex request failed", "upstream_error")
67
+ end
68
+
69
+ private
70
+
71
+ def handle_nonstream(request, response)
72
+ events = []
73
+ @codex.stream(**@protocol.responses_request(request), max_output_tokens: request.max_output_tokens) do |event|
74
+ events << event
75
+ raise RequestError.new("Codex response exceeded the event limit", status: 502) if events.length > MAX_NONSTREAM_EVENTS
76
+ end
77
+ write_json(response, 200, @protocol.chat_completion(request, events))
78
+ end
79
+
80
+ def handle_stream(request, response)
81
+ state = @protocol.stream_state(request)
82
+ cancellation = Cancellation.new
83
+ events = SizedQueue.new(16)
84
+ worker = Thread.new do
85
+ @codex.stream(**@protocol.responses_request(request), max_output_tokens: request.max_output_tokens, cancellation: cancellation) do |event|
86
+ enqueue_stream_event(events, [:event, event], cancellation)
87
+ end
88
+ enqueue_stream_event(events, [:done, nil], cancellation)
89
+ rescue StandardError => error
90
+ enqueue_stream_event(events, [:error, error], cancellation) unless cancellation.cancelled?
91
+ end
92
+ worker.report_on_exception = false
93
+
94
+ first = events.pop
95
+ if first.first == :error
96
+ worker.join
97
+ raise first.last
98
+ end
99
+
100
+ response.status = 200
101
+ response["Content-Type"] = "text/event-stream"
102
+ response["Cache-Control"] = "no-cache"
103
+ response["X-Accel-Buffering"] = "no"
104
+ response.chunked = true
105
+ response.body = proc do |output|
106
+ output.write(sse(@protocol.stream_start_chunk(state)))
107
+ done = false
108
+ current = first
109
+ until done
110
+ kind, event = current
111
+ case kind
112
+ when :event
113
+ chunks = @protocol.stream_chunks(state, event)
114
+ chunks.each { |chunk| output.write(sse(chunk)) }
115
+ done = state[:terminal]
116
+ when :done
117
+ done = true
118
+ when :error
119
+ state[:failed] = true
120
+ output.write(sse(@protocol.stream_chunks(state, "type" => "response.failed").first))
121
+ done = true
122
+ end
123
+ current = events.pop unless done
124
+ end
125
+ output.write("data: [DONE]\n\n") unless state[:failed]
126
+ ensure
127
+ cancellation.cancel! unless state[:terminal]
128
+ worker.join(2)
129
+ end
130
+ end
131
+
132
+ def enqueue_stream_event(queue, event, cancellation)
133
+ loop do
134
+ cancellation.raise_if_cancelled!
135
+ queue.push(event, true)
136
+ return
137
+ rescue ThreadError
138
+ sleep 0.01
139
+ end
140
+ end
141
+
142
+ def authorized?(request)
143
+ authorization = request["authorization"].to_s
144
+ return false unless authorization.start_with?("Bearer ")
145
+
146
+ secure_compare(authorization.delete_prefix("Bearer "), @api_key)
147
+ end
148
+
149
+ def secure_compare(left, right)
150
+ return false unless left.bytesize == right.bytesize
151
+
152
+ left.bytes.zip(right.bytes).reduce(0) { |difference, (a, b)| difference | (a ^ b) }.zero?
153
+ end
154
+
155
+ def unauthorized(response)
156
+ response["WWW-Authenticate"] = 'Bearer realm="Kward OpenRouter proxy"'
157
+ write_error(response, 401, "Unauthorized", "invalid_api_key")
158
+ end
159
+
160
+ def write_json(response, status, payload)
161
+ response.status = status
162
+ response["Content-Type"] = "application/json"
163
+ response["Cache-Control"] = "no-store"
164
+ response.body = JSON.generate(payload)
165
+ end
166
+
167
+ def write_error(response, status, message, code)
168
+ write_json(response, status, { error: { message: message, type: "invalid_request_error", code: code } })
169
+ end
170
+
171
+ def sse(chunk)
172
+ "data: #{JSON.generate(chunk)}\n\n"
173
+ end
174
+
175
+ def integer_config(key, default, min:, max:)
176
+ value = @config.fetch(key, default)
177
+ integer = Integer(value)
178
+ raise ArgumentError, "Proxy config #{key} must be between #{min} and #{max}" unless integer.between?(min, max)
179
+
180
+ integer
181
+ rescue ArgumentError, TypeError
182
+ raise ArgumentError, "Proxy config #{key} must be an integer between #{min} and #{max}"
183
+ end
184
+ end
185
+ end
186
+ end
@@ -10,7 +10,6 @@
10
10
  # ←/→ Move
11
11
  # Space Fire
12
12
  # Q / Esc Quit
13
- # Ctrl+C Force quit (handled by Kward)
14
13
  #
15
14
  # The game renders colored sprites and particle-burst explosions inside the
16
15
  # composer canvas region using the interactive mode API.
data/exe/kward CHANGED
@@ -2,6 +2,6 @@
2
2
 
3
3
  $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
4
4
 
5
- require "kward"
5
+ require "kward/entrypoint"
6
6
 
7
- Kward::CLI.new.run
7
+ Kward::Entrypoint.run
data/exe/kwsh ADDED
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
4
+
5
+ require "kward/shell/script_runner"
6
+
7
+ Kward::NativeShell::NativeProcess.standalone(ARGV, name: $0)
data/kward.gemspec CHANGED
@@ -24,10 +24,11 @@ Gem::Specification.new do |spec|
24
24
  end
25
25
  end
26
26
  spec.bindir = "exe"
27
- spec.executables = ["kward"]
27
+ spec.executables = ["kward", "kwsh"]
28
28
  spec.require_paths = ["lib"]
29
29
 
30
30
  spec.add_dependency "base64"
31
+ spec.add_dependency "fiddle"
31
32
  spec.add_dependency "nokogiri"
32
33
  spec.add_dependency "tiktoken_ruby"
33
34
  spec.add_dependency "tty-cursor"
@@ -35,4 +36,5 @@ Gem::Specification.new do |spec|
35
36
  spec.add_dependency "tty-reader"
36
37
  spec.add_dependency "tty-screen"
37
38
  spec.add_dependency "unicode-display_width"
39
+ spec.add_dependency "webrick"
38
40
  end
data/lib/kward/agent.rb CHANGED
@@ -1,3 +1,4 @@
1
+ require "securerandom"
1
2
  require_relative "cancellation"
2
3
  require_relative "model/chat_invocation"
3
4
  require_relative "compactor"
@@ -5,6 +6,7 @@ require_relative "model/context_overflow"
5
6
  require_relative "conversation"
6
7
  require_relative "plugins/turn_request"
7
8
  require_relative "events"
9
+ require_relative "turn_summary"
8
10
  require_relative "deep_copy"
9
11
  require_relative "hooks"
10
12
  require_relative "message_access"
@@ -52,6 +54,8 @@ module Kward
52
54
  started_at = @telemetry_logger.monotonic_now
53
55
  status = "completed"
54
56
  error = nil
57
+ summary = TurnSummary.new
58
+ turn_started = false
55
59
  cancellation&.raise_if_cancelled!
56
60
  system_turn = input if input.is_a?(PluginTurnRequest)
57
61
  display_input ||= system_turn.to_s if system_turn
@@ -71,19 +75,26 @@ module Kward
71
75
  else
72
76
  @conversation.append_user(input, display_content: display_input)
73
77
  end
78
+ turn_started = true
74
79
  run_hook("turn_context_build_before", payload: { message_count: @conversation.messages.length })
75
80
  auto_compact_if_needed
76
81
  run_hook("turn_context_build_after", payload: { message_count: @conversation.messages.length })
77
- answer = run_turn(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, &block)
82
+ answer = run_turn(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, summary: summary, &block)
78
83
  run_hook("turn_end", payload: { input: input, answer: answer })
79
84
  answer
80
85
  end
81
86
  rescue StandardError => e
82
- status = "failed"
87
+ status = e.is_a?(Cancellation::CancelledError) ? "canceled" : "failed"
83
88
  error = e
84
89
  raise e
85
90
  ensure
86
- log_turn(duration_ms: @telemetry_logger.duration_ms(started_at), status: status, error: error)
91
+ elapsed_ms = @telemetry_logger.duration_ms(started_at)
92
+ log_turn(duration_ms: elapsed_ms, status: status, error: error)
93
+ if turn_started
94
+ result = summary.finish(status: status, elapsed_ms: elapsed_ms)
95
+ @conversation.finish_turn(result)
96
+ block&.call(Events::TurnSummary.new(summary: result))
97
+ end
87
98
  end
88
99
 
89
100
  # Runs model calls until the assistant returns an answer without pending
@@ -91,16 +102,18 @@ module Kward
91
102
  #
92
103
  # @yieldparam event [Object] streamed turn event for frontends
93
104
  # @return [String] final assistant answer
94
- def run_turn(on_reasoning_delta: nil, on_retry: nil, cancellation: nil, steering: nil, options: {}, tool_registry: nil)
105
+ def run_turn(on_reasoning_delta: nil, on_retry: nil, cancellation: nil, steering: nil, options: {}, tool_registry: nil, summary: nil)
95
106
  overflow_retried = false
107
+ image_turn_id = SecureRandom.uuid
96
108
  steering_state = build_steering_state(steering) do |event|
97
109
  yield event if block_given?
98
110
  end
111
+ registry = tool_registry || @tool_registry
99
112
  loop do
100
113
  cancellation&.raise_if_cancelled!
101
114
  auto_compact_if_needed
102
115
  begin
103
- message = chat(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry) do |event|
116
+ message = chat(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, summary: summary) do |event|
104
117
  yield event if block_given?
105
118
  end
106
119
  rescue StandardError => e
@@ -126,14 +139,22 @@ module Kward
126
139
  end
127
140
 
128
141
  tool_calls.each do |tool_call|
142
+ image = nil
143
+ image_published = false
129
144
  cancellation&.raise_if_cancelled!
145
+ summary&.tool_call
130
146
  yield Events::ToolCall.new(tool_call: tool_call) if block_given?
131
147
  tool_started_at = @telemetry_logger.monotonic_now
132
148
  content = nil
133
149
  status = "completed"
134
150
  error = nil
135
151
  begin
136
- content = (tool_registry || @tool_registry).dispatch(tool_call, @conversation, cancellation: cancellation)
152
+ if ToolCall.name(tool_call) == Tools::GenerateImage::NAME && registry.respond_to?(:discard_generated_image)
153
+ provider = message["provider"] || message[:provider]
154
+ content = registry.dispatch(tool_call, @conversation, cancellation: cancellation, image_context: { provider: provider, turn_id: image_turn_id }) { |preview| image = preview }
155
+ else
156
+ content = registry.dispatch(tool_call, @conversation, cancellation: cancellation)
157
+ end
137
158
  rescue StandardError => e
138
159
  status = "failed"
139
160
  error = e
@@ -146,7 +167,14 @@ module Kward
146
167
  elapsed_ms = @telemetry_logger.duration_ms(tool_started_at)
147
168
  yield Events::ToolUpdate.new(tool_call: tool_call, content: content, elapsed_ms: elapsed_ms)
148
169
  yield Events::ToolResult.new(tool_call: tool_call, content: content)
170
+ if image
171
+ cancellation&.raise_if_cancelled!
172
+ yield Events::ImageReady.new(tool_call: tool_call, image: image)
173
+ image_published = true
174
+ end
149
175
  end
176
+ ensure
177
+ registry.discard_generated_image(@conversation, image.id) if image && !image_published
150
178
  end
151
179
  steered_after_tools = append_steering_events(steering_state)
152
180
  yield Events::SteeringApplied.new(count: steered_after_tools) if block_given? && steered_after_tools.positive?
@@ -229,7 +257,7 @@ module Kward
229
257
  @warning_sink ? @warning_sink.call(message) : warn(message)
230
258
  end
231
259
 
232
- def chat(on_reasoning_delta: nil, on_retry: nil, cancellation: nil, steering: nil, options: {}, tool_registry: nil)
260
+ def chat(on_reasoning_delta: nil, on_retry: nil, cancellation: nil, steering: nil, options: {}, tool_registry: nil, summary: nil)
233
261
  reasoning_delta = lambda do |delta|
234
262
  cancellation&.raise_if_cancelled!
235
263
  on_reasoning_delta&.call(delta)
@@ -245,15 +273,19 @@ module Kward
245
273
  end
246
274
  retry_callback = lambda do |retry_info|
247
275
  cancellation&.raise_if_cancelled!
276
+ summary&.retry
248
277
  event = Events::Retry.new(**retry_info)
249
278
  on_retry&.call(event)
250
279
  yield event if block_given?
251
280
  end
252
281
  registry = tool_registry || @tool_registry
282
+ provider = options[:provider] || @conversation.provider
283
+ schema_provider = provider || (@client.current_provider if @client.respond_to?(:current_provider))
284
+ schemas = registry.respond_to?(:schemas_for) ? registry.schemas_for(schema_provider) : registry.schemas
253
285
  request = {
254
286
  messages: @conversation.context_messages,
255
- tools: registry.schemas,
256
- provider: options[:provider] || @conversation.provider,
287
+ tools: schemas,
288
+ provider: provider,
257
289
  model: options[:model] || @conversation.model,
258
290
  reasoning: options[:reasoning] || @conversation.reasoning_effort,
259
291
  provider_required: @strict_provider
@@ -263,6 +295,7 @@ module Kward
263
295
  return { "role" => "assistant", "content" => hook_denied_answer(before) } if before.denied?
264
296
 
265
297
  run_hook("turn_model_request_before", payload: request)
298
+ summary&.model_request
266
299
  response = ChatInvocation.call(
267
300
  @client,
268
301
  request[:messages] || request["messages"],
@@ -280,6 +313,7 @@ module Kward
280
313
  provider_required: request[:provider_required] || request["provider_required"]
281
314
  }
282
315
  )
316
+ summary&.record(response)
283
317
  run_hook("model_response_after_parse", payload: { message: response })
284
318
  run_hook("turn_model_response_complete", payload: { message: response })
285
319
  response
@@ -19,7 +19,7 @@ module Kward
19
19
  end
20
20
 
21
21
  def one_shot_prompt_argument
22
- prompt = @argv.join(" ").strip
22
+ prompt = (@argv.first == "prompt" ? @argv[1..] : []).join(" ").strip
23
23
  prompt.empty? ? nil : prompt
24
24
  end
25
25
 
@@ -53,7 +53,7 @@ module Kward
53
53
  lines << heading.call("Examples")
54
54
  lines.concat help_examples.map { |example| " #{colored(example, :green, :bold)}" }
55
55
  lines << ""
56
- lines << "Command names take precedence. Anything else is sent as a one-shot prompt."
56
+ lines << "Use `kward prompt <text>` to run a one-shot prompt. Unknown commands are not sent to the model."
57
57
  @prompt.say lines.join("\n")
58
58
  end
59
59
 
@@ -66,9 +66,10 @@ module Kward
66
66
  ["kward init", "Install starter prompts and PRINCIPLES.md"]
67
67
  ],
68
68
  "Work" => [
69
- ["kward \"PROMPT\"", "Run a one-shot prompt"],
70
- ["kward --filter \"INSTRUCTION\"", "Filter standard input"],
69
+ ["kward prompt \"PROMPT\"", "Run a one-shot prompt"],
70
+ ["kward filter \"INSTRUCTION\"", "Filter standard input"],
71
71
  ["kward edit <filename>", "Open a file in the integrated editor"],
72
+ ["kward shell", "Start a standalone shell; use ? to ask the agent"],
72
73
  ["kward sysprompt [--raw]", "Inspect the effective system prompt"]
73
74
  ],
74
75
  "Manage" => [
@@ -94,8 +95,8 @@ module Kward
94
95
  [
95
96
  ["--working-directory=PATH", "Run Kward from PATH"],
96
97
  ["--mode=MODE", "Execution mode: auto, chat, oneshot, filter"],
97
- ["--filter", "Shortcut for --mode filter"],
98
98
  ["--skip-config", "Ignore the main config file for this run"],
99
+ ["--ignore-local-instructions", "Ignore workspace AGENTS.md files and project skills for this run"],
99
100
  ["--help, -h", "Show help"],
100
101
  ["--version, -v", "Show the installed version"]
101
102
  ]
@@ -104,9 +105,9 @@ module Kward
104
105
  def help_examples
105
106
  [
106
107
  "kward",
107
- "kward \"Explain this project\"",
108
- "git diff | kward \"Summarize the main changes\"",
109
- "echo Hello | kward --filter \"Translate to German\"",
108
+ "kward prompt \"Explain this project\"",
109
+ "git diff | kward prompt \"Summarize the main changes\"",
110
+ "echo Hello | kward filter \"Translate to German\"",
110
111
  "kward login openrouter",
111
112
  "kward edit lib/main.rb",
112
113
  "kward stats tokens today --bucket hour"
@@ -144,6 +145,16 @@ module Kward
144
145
  description: "Show or clear saved provider credentials without printing secrets.",
145
146
  examples: ["kward auth status", "kward auth status --all", "kward auth logout"]
146
147
  },
148
+ "filter" => {
149
+ usage: "kward filter <instruction>",
150
+ description: "Filter standard input according to an instruction.",
151
+ examples: ["echo Hello | kward filter \"Translate to German\""]
152
+ },
153
+ "prompt" => {
154
+ usage: "kward prompt <text>",
155
+ description: "Run a one-shot prompt.",
156
+ examples: ["kward prompt \"Explain this project\"", "git diff | kward prompt \"Review this diff\""]
157
+ },
147
158
  "init" => {
148
159
  usage: "kward init",
149
160
  description: "Install starter prompts and base PRINCIPLES.md into your config directory.",
@@ -169,6 +180,11 @@ module Kward
169
180
  description: "Open a file in the integrated editor.",
170
181
  examples: ["kward edit lib/main.rb", "kward edit ~/notes/todo.md"]
171
182
  },
183
+ "shell" => {
184
+ usage: "kward shell [-i] [shell-options] [-c command [name [args...]] | -s [args...] | file [args...]]",
185
+ description: "Run native kwsh directly in your terminal or read commands from a file or standard input. The agent loads only when you use ? in an interactive terminal; no composer is started.",
186
+ examples: ["kward shell", "kward shell -o vi", "kward shell -c 'printf \"%s\\n\" \"$PWD\"'"]
187
+ },
172
188
  "sysprompt" => {
173
189
  usage: "kward sysprompt [--raw]",
174
190
  description: "Inspect the effective system prompt for a new conversation in the current workspace.",
@@ -257,8 +273,8 @@ module Kward
257
273
  break
258
274
  when "--skip-config"
259
275
  @skip_config = true
260
- when "--filter"
261
- @requested_mode = "filter"
276
+ when "--ignore-local-instructions"
277
+ @ignore_local_instructions = true
262
278
  when "--mode"
263
279
  index += 1
264
280
  raise ArgumentError, "Missing value for --mode" if index >= arguments.length
@@ -278,7 +294,21 @@ module Kward
278
294
  end
279
295
  index += 1
280
296
  end
281
- remaining
297
+ ConfigFiles.skip_config = @skip_config
298
+ extract_plugin_startup_options(remaining)
299
+ end
300
+
301
+ def extract_plugin_startup_options(arguments)
302
+ return arguments if @prompt_delimited || arguments.none? { |argument| argument.start_with?("--") }
303
+
304
+ registry = discover_plugin_registry
305
+ arguments.reject do |argument|
306
+ next false unless registry.startup_option_for(argument)
307
+ raise ArgumentError, "Only one plugin startup option may be selected" if @startup_option_name
308
+
309
+ @startup_option_name = argument
310
+ true
311
+ end
282
312
  end
283
313
 
284
314
  def normalized_execution_mode(value)
@@ -142,6 +142,9 @@ module Kward
142
142
  auto_summarize_memory(agent.conversation) if agent.respond_to?(:conversation) && !suppress_transcript && queued_inputs.empty? && !cancelled
143
143
  queued_inputs
144
144
  ensure
145
+ if stream_state && !suppress_transcript && !busy_replacement_agent?
146
+ print_turn_summary(stream_state.delete(:turn_summary))
147
+ end
145
148
  @prompt.finish_busy_input if @prompt.respond_to?(:finish_busy_input)
146
149
  if @prompt.respond_to?(:show_completion) && !busy_replacement_agent?
147
150
  completion = if cancelled
@@ -213,6 +216,8 @@ module Kward
213
216
 
214
217
  def handle_interactive_event(event, markdown_chunks, stream_state)
215
218
  case event
219
+ when Events::TurnSummary
220
+ stream_state[:turn_summary] = event.summary
216
221
  when Events::ReasoningDelta
217
222
  stream_state[:streamed] = true
218
223
  update_busy_activity("reasoning")
@@ -384,7 +389,9 @@ module Kward
384
389
  def run_blocking_interactive_turn(agent, input, display_input: nil, tool_registry: nil, suppress_transcript: false, on_complete: nil)
385
390
  streamed = false
386
391
  markdown_chunks = []
392
+ summary = nil
387
393
  answer = agent.ask(input, **agent_display_options(display_input, tool_registry: tool_registry)) do |event|
394
+ summary = event.summary if event.is_a?(Events::TurnSummary)
388
395
  streamed = true if !suppress_transcript && render_blocking_turn_event(event, markdown_chunks, tool_line_limit: INTERACTIVE_TOOL_OUTPUT_LINE_LIMIT)
389
396
  end
390
397
  flush_markdown_deltas(markdown_chunks) if streamed
@@ -393,6 +400,9 @@ module Kward
393
400
  auto_summarize_memory(agent.conversation) if agent.respond_to?(:conversation) && !suppress_transcript
394
401
  on_complete&.call(successful: true, cancelled: false, error: nil, answer: answer)
395
402
  []
403
+ ensure
404
+ flush_markdown_deltas(markdown_chunks) if markdown_chunks && !suppress_transcript
405
+ print_turn_summary(summary) unless suppress_transcript
396
406
  end
397
407
 
398
408
  def agent_display_options(display_input, tool_registry: nil)
@@ -10,8 +10,12 @@ module Kward
10
10
  @prompt_templates ||= ConfigFiles.prompt_templates(reserved_commands: builtin_slash_command_names)
11
11
  end
12
12
 
13
+ def discover_plugin_registry
14
+ @plugin_registry ||= PluginRegistry.load(reserved_commands: reserved_slash_command_names)
15
+ end
16
+
13
17
  def plugin_registry
14
- @plugin_registry ||= PluginRegistry.load(reserved_commands: reserved_slash_command_names).tap(&:start!)
18
+ discover_plugin_registry.tap(&:start!)
15
19
  end
16
20
 
17
21
  def plugin_commands
@@ -357,7 +357,10 @@ module Kward
357
357
  end
358
358
 
359
359
  def footer_tool_schemas
360
- @footer_tool_registry&.schemas || []
360
+ return [] unless @footer_tool_registry
361
+ return @footer_tool_registry.schemas unless @footer_tool_registry.respond_to?(:schemas_for)
362
+
363
+ @footer_tool_registry.schemas_for(current_footer_conversation.provider)
361
364
  end
362
365
 
363
366
  def current_footer_conversation
@@ -1,3 +1,5 @@
1
+ require_relative "../transcripts/turn_summary_formatter"
2
+
1
3
  # Namespace for the Kward CLI agent runtime.
2
4
  module Kward
3
5
  # Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.
@@ -48,8 +50,7 @@ module Kward
48
50
  print_user_transcript(
49
51
  CLITranscriptFormatter.user_transcript_input(message),
50
52
  display_input: CLITranscriptFormatter.user_display_text(message),
51
- attachment_references: CLITranscriptFormatter.image_references(message),
52
- image_parts: CLITranscriptFormatter.image_parts(message)
53
+ attachment_references: CLITranscriptFormatter.image_references(message)
53
54
  )
54
55
  when "assistant"
55
56
  render_reasoning(message)
@@ -64,9 +65,22 @@ module Kward
64
65
  else
65
66
  render_transcript_block(role.to_s.capitalize, CLITranscriptFormatter.content_text(message_content(message)))
66
67
  end
68
+ print_turn_summary(MessageAccess.value(message, :turn_summary))
67
69
  end
68
70
  end
69
71
 
72
+ def turn_summary_text(summary)
73
+ return "" unless summary.is_a?(Hash)
74
+
75
+ width = [TTY::Screen.width - 1, 1].max if $stdout.tty?
76
+ TurnSummaryFormatter.render(summary, mode: ConfigFiles.transcript_turn_stats, width: width)
77
+ end
78
+
79
+ def print_turn_summary(summary)
80
+ text = turn_summary_text(summary)
81
+ write_prompt_transcript("\n#{colored(text, :metadata)}\n") unless text.empty?
82
+ end
83
+
70
84
  def render_reasoning(message)
71
85
  CLITranscriptFormatter.reasoning_blocks(message).each do |reasoning|
72
86
  render_transcript_block("Reasoning", reasoning)
@@ -221,14 +235,15 @@ module Kward
221
235
  end
222
236
 
223
237
  # Writes the user transcript output for the terminal CLI flow.
224
- def print_user_transcript(input, display_input: nil, attachment_references: nil, image_parts: nil)
238
+ def print_user_transcript(input, display_input: nil, attachment_references: nil)
225
239
  visible_input = display_input.nil? ? input : display_input
226
- write_prompt_transcript("\n#{colored("❯ You>", :blue, :bold)} #{visible_input}\n")
240
+ write_prompt_transcript("\n#{colored("You>", :blue, :bold)} #{visible_input}\n")
227
241
  # System-turn instructions are plain text, never image attachments.
228
242
  return if input.is_a?(PluginTurnRequest)
229
243
 
244
+ # Terminal graphics are not tracked by the text-only scroll/redraw buffer.
245
+ # Keep transcript attachments as badges; /files owns image previews.
230
246
  print_attachment_badges(input, references: attachment_references)
231
- print_pasted_images(input, image_parts: image_parts)
232
247
  end
233
248
 
234
249
  # Writes the attachment badges output for the terminal CLI flow.
@@ -289,27 +304,6 @@ module Kward
289
304
  "#{formatted} #{unit}"
290
305
  end
291
306
 
292
- # Writes the pasted images output for the terminal CLI flow.
293
- def print_pasted_images(input, image_parts: nil)
294
- parts = image_parts || Kward::ImageAttachments.image_parts_from_text(input)
295
- protocol = @prompt.inline_image_protocol if @prompt.respond_to?(:inline_image_protocol)
296
- parts.each do |part|
297
- next if @prompt.respond_to?(:inline_image_protocol) && protocol.nil?
298
-
299
- part = Kward::ImageAttachments.terminal_image_part(part, protocol) if protocol
300
- next if protocol && part.nil?
301
-
302
- sequence = Kward::ImageAttachments.terminal_image_sequence(part, protocol: protocol)
303
- next unless sequence
304
-
305
- if @prompt.respond_to?(:say_visual)
306
- @prompt.say_visual(sequence)
307
- else
308
- @prompt.say(sequence)
309
- end
310
- end
311
- end
312
-
313
307
  # Writes the block delta output for the terminal CLI flow.
314
308
  def print_block_delta(label, delta)
315
309
  if prompt_interface?
@@ -413,8 +407,7 @@ module Kward
413
407
  end
414
408
 
415
409
  def transcript_marker(label)
416
- marker = "#{transcript_label(label)}>"
417
- label == "Assistant" ? "✦ #{marker}" : marker
410
+ "#{transcript_label(label)}>"
418
411
  end
419
412
 
420
413
  def label_styles(label)