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,82 @@
1
+ require "io/console"
2
+ require "json"
3
+ require "socket"
4
+ require_relative "native_runtime"
5
+
6
+ module Kward
7
+ module NativeShell
8
+ # A single-threaded interpreter process owns the terminal and mutable shell
9
+ # state. Requests/state use a private socket, never terminal input/output.
10
+ class Worker
11
+ def self.run(descriptor)
12
+ control = UNIXSocket.for_fd(descriptor)
13
+ control.close_on_exec = true
14
+ control.sync = true
15
+ $stdout.sync = true
16
+ $stderr.sync = true
17
+ runtime = nil
18
+ Signal.trap("INT") { raise Interrupt }
19
+ %w[TERM HUP USR2].each { |signal| Signal.trap(signal) { raise SystemExit } }
20
+ %w[TSTP TTIN TTOU].each { |signal| Signal.trap(signal, "IGNORE") }
21
+
22
+ line = control.gets
23
+ return unless line
24
+ request = JSON.parse(line)
25
+ runtime = Runtime.new(cwd: request.fetch("cwd"), env: ENV.to_h, aliases: request.fetch("aliases", {}), interactive: true, process_owned: true)
26
+ runtime.with_signals do
27
+ loop do
28
+ status = begin
29
+ $stdin.echo = true
30
+ if request["config"]
31
+ apply_configuration(runtime, request["config"])
32
+ elsif request["suppress_git_pager"]
33
+ runtime.with_pager_suppressed { runtime.run(request.fetch("command")) }
34
+ else
35
+ runtime.run(request.fetch("command"))
36
+ end
37
+ rescue Interrupt
38
+ 130
39
+ ensure
40
+ $stdin.echo = false
41
+ end
42
+ status = runtime.finish if runtime.exited
43
+ $stdout.write("#{request.fetch('marker')}:#{status}:\n")
44
+ control.puts(JSON.generate(cwd: runtime.cwd, env: runtime.environment, aliases: runtime.aliases, exited: runtime.exited))
45
+ break if runtime.exited
46
+ loop do
47
+ begin
48
+ runtime.poll_signals
49
+ break if runtime.exited || IO.select([control], nil, nil, 0.05)
50
+ rescue Interrupt
51
+ # Ctrl-C at an idle prompt cancels input, not the shell lifetime.
52
+ end
53
+ end
54
+ if runtime.exited
55
+ runtime.finish
56
+ break
57
+ end
58
+ line = control.gets
59
+ break unless line
60
+ request = JSON.parse(line)
61
+ end
62
+ end
63
+ rescue EOFError, Errno::EIO, Errno::EPIPE
64
+ nil
65
+ ensure
66
+ runtime&.close
67
+ end
68
+
69
+ def self.apply_configuration(runtime, config)
70
+ config.fetch("env", {}).each do |key, value|
71
+ status = runtime.run("export #{key}=#{Shellwords.escape(value)}")
72
+ return status unless status.zero?
73
+ end
74
+ runtime.aliases.merge!(config.fetch("aliases", {}))
75
+ runtime.run(":")
76
+ end
77
+ private_class_method :apply_configuration
78
+ end
79
+ end
80
+ end
81
+
82
+ Kward::NativeShell::Worker.run(Integer(ARGV.fetch(0))) if $PROGRAM_NAME == __FILE__
@@ -2,6 +2,10 @@ require "io/console"
2
2
  require "pty"
3
3
  require "securerandom"
4
4
  require "shellwords"
5
+ require "json"
6
+ require "socket"
7
+ require "rbconfig"
8
+ require_relative "native_syntax"
5
9
  require_relative "../terminal/ansi"
6
10
  require_relative "kwsh"
7
11
  require_relative "kwshrc"
@@ -10,10 +14,9 @@ require_relative "../pty/detached_run"
10
14
 
11
15
  # Namespace for the Kward CLI agent runtime.
12
16
  module Kward
13
- # Owns one interactive shell process and serializes user and agent commands.
14
- #
15
- # The process is kept alive between commands so shell variables, functions,
16
- # aliases, directory changes, and child-shell state belong to one session.
17
+ # Owns one native kwsh interpreter process and serializes user and agent
18
+ # commands. The PTY owns terminal input/output; a private socket carries
19
+ # interpreter requests and authoritative shell state.
17
20
  class PersistentShellSession
18
21
  Result = Kwsh::Result
19
22
  InteractiveResult = Struct.new(:exit_status, :input_forwarded, :tab_action, :background, keyword_init: true)
@@ -29,17 +32,40 @@ module Kward
29
32
 
30
33
  READ_SIZE = 4_096
31
34
  STARTUP_TIMEOUT_SECONDS = 5
32
- STTY_COMMAND = if File.executable?("/bin/stty")
33
- "/bin/stty"
34
- elsif File.executable?("/usr/bin/stty")
35
- "/usr/bin/stty"
36
- else
37
- "stty"
38
- end.freeze
39
- STATEFUL_COMMANDS = %w[alias cd export pwd unset unalias].freeze
35
+ STATEFUL_COMMANDS = %w[alias cd export pwd unset unalias .].freeze
40
36
 
41
37
  attr_reader :cwd, :last_command, :timeout_seconds
42
38
 
39
+ def exited?
40
+ @native_exited == true
41
+ end
42
+
43
+ def input_prompt_label
44
+ @pending_source ? "Shell ... >" : prompt_label
45
+ end
46
+
47
+ def compose_input(line)
48
+ return line if !@pending_source && line.start_with?("?")
49
+
50
+ source = @pending_source ? "#{@pending_source}\n#{line}" : line
51
+ if incomplete_input?(source)
52
+ @pending_source = source
53
+ nil
54
+ else
55
+ @pending_source = nil
56
+ source
57
+ end
58
+ end
59
+
60
+ def incomplete_input?(source)
61
+ NativeShell::Parser.parse(source.sub(/\A\s*(?:capture|pty)\s+/, ""), aliases: @aliases || {})
62
+ false
63
+ rescue NativeShell::IncompleteInput
64
+ true
65
+ rescue NativeShell::SyntaxError
66
+ false
67
+ end
68
+
43
69
  def initialize(cwd: Dir.pwd, env: ENV.to_h, shell: Kwsh::DEFAULT_SHELL, configured_env: {}, aliases: {}, timeout_seconds: Kwsh::DEFAULT_TIMEOUT_SECONDS, max_output_bytes: Kwsh::DEFAULT_MAX_OUTPUT_BYTES, window_size_provider: nil)
44
70
  @cwd = File.expand_path(cwd.to_s.empty? ? Dir.pwd : cwd.to_s)
45
71
  @base_env = env.to_h.transform_keys(&:to_s).transform_values(&:to_s)
@@ -83,29 +109,39 @@ module Kward
83
109
  return Result.new(output: "", exit_status: 0) if command.empty?
84
110
 
85
111
  expanded_command = expand_alias(command)
86
- words = shell_words(expanded_command)
87
- sync_runtime_state(words)
88
- result = if words.empty?
112
+ native_command = command
113
+ syntax_command = command
114
+ if expanded_command.match?(/\A\s*(?:capture|pty)(?:\s|\z)/)
115
+ syntax_command = expanded_command.sub(/\A\s*(?:capture|pty)\s+/, "")
116
+ end
117
+ tree = NativeShell::Parser.parse(syntax_command, aliases: @aliases)
118
+ words = routing_words(expanded_command, tree)
119
+ result = if tree.values.first.empty?
89
120
  Result.new(output: "", exit_status: 0)
90
121
  elsif words.first == "clear"
91
122
  Result.new(output: "", exit_status: 0, clear: true)
92
123
  elsif %w[exit logout].include?(words.first)
93
- exit_result(command, words)
124
+ execute_command(expanded_command.sub(/\Alogout\b/, "exit"), display_command: command, cancellation: cancellation, &block)
94
125
  elsif words.first == "capture"
95
126
  capture_result(command, expanded_command, cancellation: cancellation, &block)
96
127
  elsif words.first == "pty"
97
128
  interactive_result(command, expanded_command)
98
- elsif %w[source .].include?(words.first)
129
+ elsif words.first == "source"
99
130
  source_result(command, words)
100
- elsif (editor_result = editor_command_result(command))
131
+ elsif words.any? && (editor_result = editor_command_result(command))
101
132
  editor_result
102
133
  elsif stateful_command?(words)
103
- execute_command(expanded_command, display_command: command, cancellation: cancellation, &block)
134
+ execute_command(native_command, display_command: command, cancellation: cancellation, &block)
104
135
  else
105
- Result.new(output: command_echo(command), exit_status: 0, interactive_command: expanded_command)
136
+ Result.new(output: command_echo(command), exit_status: 0, interactive_command: native_command)
106
137
  end
107
138
  remember_result(command, result)
108
139
  result
140
+ rescue NativeShell::SyntaxError
141
+ # Let the interpreter record the failure too, so the next $? is correct.
142
+ result = execute_command(syntax_command, display_command: command, cancellation: cancellation, &block)
143
+ remember_result(command, result)
144
+ result
109
145
  rescue ArgumentError => e
110
146
  result = Result.new(output: "#{command_echo(command)}kwsh: #{e.message}\n", exit_status: 2)
111
147
  remember_result(command, result)
@@ -170,10 +206,16 @@ module Kward
170
206
  end
171
207
 
172
208
  def expand_alias(command, interactive: false)
209
+ token = NativeShell::Lexer.new(command).next_token&.value
210
+ return command unless token.is_a?(NativeShell::Word) && token.literal
173
211
  @routing_shell.expand_alias(command, interactive: interactive)
212
+ rescue NativeShell::SyntaxError
213
+ command
174
214
  end
175
215
 
176
216
  def editor_command_result(command, display_command: command)
217
+ token = NativeShell::Lexer.new(command).next_token&.value
218
+ return unless token.is_a?(NativeShell::Word) && token.literal
177
219
  @routing_shell.editor_command_result(command, display_command: display_command)
178
220
  end
179
221
 
@@ -187,6 +229,7 @@ module Kward
187
229
  @write_mutex.synchronize do
188
230
  @reader&.close unless @reader&.closed?
189
231
  @writer&.close unless @writer&.closed?
232
+ @control&.close unless @control&.closed?
190
233
  end
191
234
  @process_thread&.join(0.5)
192
235
  @process_thread&.kill if @process_thread&.alive?
@@ -229,19 +272,27 @@ module Kward
229
272
  end
230
273
 
231
274
  def start_process
275
+ @protocol_pending = false
232
276
  ready = Queue.new
233
- process_env = @env.merge("PS1" => "", "PS2" => "")
277
+ @control, child_control = UNIXSocket.pair
278
+ @control.sync = true
279
+ worker = File.expand_path("native_worker.rb", __dir__)
234
280
  @process_thread = Thread.new do
235
281
  begin
236
- PTY.spawn(process_env, @shell, "-i", chdir: @cwd) do |reader, writer, pid|
282
+ PTY.spawn(@env, RbConfig.ruby, worker, "3", 3 => child_control, chdir: @cwd, unsetenv_others: true) do |reader, writer, pid|
283
+ child_control.close
237
284
  @reader = reader
238
285
  @writer = writer
239
286
  @pid = pid
240
287
  ready << true
241
- sleep 0.05 until @closed
288
+ until @closed
289
+ sleep 0.01 unless drain_idle_output
290
+ end
242
291
  end
243
292
  rescue StandardError => e
244
293
  ready << e
294
+ ensure
295
+ child_control.close unless child_control.closed?
245
296
  end
246
297
  end
247
298
  started = ready.pop
@@ -249,6 +300,7 @@ module Kward
249
300
 
250
301
  @reader.sync = true
251
302
  @writer.sync = true
303
+ @window_size = nil
252
304
  update_window_size
253
305
  end
254
306
 
@@ -259,12 +311,14 @@ module Kward
259
311
  update_cwd(protocol[:cwd])
260
312
  end
261
313
 
262
- def execute_protocol(command, input: nil, sink: nil, timeout_seconds: nil, max_output_bytes: @max_output_bytes, cancellation: nil, suppress_git_pager: false, tab_action_handler: nil, on_detach: nil)
314
+ def execute_protocol(command, input: nil, sink: nil, timeout_seconds: nil, max_output_bytes: @max_output_bytes, cancellation: nil, suppress_git_pager: false, tab_action_handler: nil, on_detach: nil, config: nil)
263
315
  @command_mutex.synchronize do
264
316
  ensure_open
265
317
  cancellation&.raise_if_cancelled!
266
318
  marker = next_marker
267
- write_protocol_command(command, marker, suppress_git_pager: suppress_git_pager)
319
+ @protocol_pending = true
320
+ update_window_size
321
+ write_protocol_command(command, marker, suppress_git_pager: suppress_git_pager, config: config)
268
322
  read_until_marker(
269
323
  marker,
270
324
  input: input,
@@ -284,48 +338,19 @@ module Kward
284
338
  raise
285
339
  end
286
340
 
287
- def write_protocol_command(command, marker, suppress_git_pager: false)
288
- escaped_command = Shellwords.escape(command.to_s)
289
- pager_setup, pager_restore = git_pager_protocol(marker, suppress: suppress_git_pager)
290
- protocol = <<~SHELL
291
- if true; then
292
- if [ -n "${ZSH_VERSION-}" ]; then unsetopt zle 2>/dev/null; fi
293
- PS1=''
294
- PS2=''
295
- export PS1 PS2
296
- #{STTY_COMMAND} echo
297
- #{pager_setup}
298
- if eval #{escaped_command}; then __kward_status=$?; else __kward_status=$?; fi
299
- #{pager_restore}
300
- __kward_cwd=$(pwd 2>/dev/null)
301
- #{STTY_COMMAND} -echo
302
- printf '#{marker}:%s:%s\\n' "$__kward_status" "$__kward_cwd"
303
- fi
304
- SHELL
305
- write_raw(protocol)
306
- end
307
-
308
- def git_pager_protocol(marker, suppress:)
309
- return ["", ""] unless suppress
310
-
311
- was_set = "#{marker}_GIT_PAGER_WAS_SET"
312
- saved_value = "#{marker}_GIT_PAGER_VALUE"
313
- setup = <<~SHELL
314
- #{was_set}=${GIT_PAGER+x}
315
- #{saved_value}=${GIT_PAGER-}
316
- GIT_PAGER=cat
317
- export GIT_PAGER
318
- SHELL
319
- restore = <<~SHELL
320
- if [ "$#{was_set}" = x ]; then
321
- GIT_PAGER="$#{saved_value}"
322
- export GIT_PAGER
323
- else
324
- unset GIT_PAGER
325
- fi
326
- unset #{was_set} #{saved_value}
327
- SHELL
328
- [setup, restore]
341
+ def write_protocol_command(command, marker, suppress_git_pager: false, config: nil)
342
+ @control.puts(JSON.generate(command: command, marker: marker, cwd: @cwd, aliases: @aliases, suppress_git_pager: suppress_git_pager, config: config))
343
+ end
344
+
345
+ def receive_runtime_state
346
+ state = JSON.parse(@control.gets || raise(IOError, "The native shell control channel closed."))
347
+ @env = state.fetch("env")
348
+ @aliases = state.fetch("aliases")
349
+ @native_exited = state.fetch("exited")
350
+ update_cwd(state.fetch("cwd"))
351
+ @routing_shell = build_routing_shell
352
+ @completion_shell = nil
353
+ @cwd
329
354
  end
330
355
 
331
356
  def read_until_marker(marker, input:, sink:, timeout_seconds:, max_output_bytes:, cancellation:, tab_action_handler: nil, on_detach: nil, initial_buffer: nil)
@@ -379,7 +404,8 @@ module Kward
379
404
  end
380
405
  parsed = extract_marker(buffer, marker)
381
406
  if parsed
382
- before, status, cwd = parsed
407
+ before, status, = parsed
408
+ cwd = receive_runtime_state
383
409
  captured_bytes, truncated = emit_output(
384
410
  before,
385
411
  sink,
@@ -389,6 +415,7 @@ module Kward
389
415
  max_output_bytes
390
416
  )
391
417
  drain_prompt_output
418
+ @protocol_pending = false
392
419
  return {
393
420
  output: captured,
394
421
  status: status,
@@ -414,51 +441,54 @@ module Kward
414
441
  end
415
442
  end
416
443
 
444
+ input_chunk = :wait_readable
417
445
  if input && readable.include?(input)
418
446
  input_chunk = input.read_nonblock(READ_SIZE, exception: false)
419
- if input_chunk.nil?
420
- input = nil
421
- elsif input_chunk != :wait_readable
422
- filtered = tab_action_handler&.call(input_chunk)
423
- input_chunk = filtered[:input].to_s if filtered
424
- unless input_chunk.empty?
425
- notify_input_forwarded(sink)
426
- write_raw(input_chunk)
427
- input_forwarded = true
428
- end
429
- if filtered && filtered[:tab_action]
430
- if on_detach
431
- detached_sink = on_detach.call
432
- detached = detach_protocol(
433
- marker,
434
- sink: detached_sink,
435
- timeout_seconds: timeout_seconds,
436
- max_output_bytes: max_output_bytes,
437
- initial_buffer: buffer,
438
- input_forwarded: input_forwarded
439
- )
440
- raise CommandInterrupted.new(
441
- output: captured,
442
- status: 0,
443
- cwd: @cwd,
444
- input_forwarded: input_forwarded,
445
- tab_action: filtered[:tab_action],
446
- truncated: truncated,
447
- background: detached
448
- )
449
- end
450
-
451
- interrupt_process
452
- raise CommandInterrupted.new(
453
- output: captured,
454
- status: 130,
455
- cwd: @cwd,
456
- input_forwarded: input_forwarded,
457
- tab_action: filtered[:tab_action],
458
- truncated: truncated
459
- )
460
- end
447
+ input = nil if input_chunk.nil?
448
+ end
449
+ filtered = nil
450
+ if input_chunk.nil? || input_chunk == :wait_readable
451
+ input_chunk = tab_action_handler.flush_pending_escape if tab_action_handler.respond_to?(:flush_pending_escape)
452
+ else
453
+ filtered = tab_action_handler&.call(input_chunk)
454
+ input_chunk = filtered[:input].to_s if filtered
455
+ end
456
+ if input_chunk.is_a?(String) && !input_chunk.empty?
457
+ notify_input_forwarded(sink)
458
+ write_raw(input_chunk)
459
+ input_forwarded = true
460
+ end
461
+ if filtered && filtered[:tab_action]
462
+ if on_detach
463
+ detached_sink = on_detach.call
464
+ detached = detach_protocol(
465
+ marker,
466
+ sink: detached_sink,
467
+ timeout_seconds: timeout_seconds,
468
+ max_output_bytes: max_output_bytes,
469
+ initial_buffer: buffer,
470
+ input_forwarded: input_forwarded
471
+ )
472
+ raise CommandInterrupted.new(
473
+ output: captured,
474
+ status: 0,
475
+ cwd: @cwd,
476
+ input_forwarded: input_forwarded,
477
+ tab_action: filtered[:tab_action],
478
+ truncated: truncated,
479
+ background: detached
480
+ )
461
481
  end
482
+
483
+ interrupt_process
484
+ raise CommandInterrupted.new(
485
+ output: captured,
486
+ status: 130,
487
+ cwd: @cwd,
488
+ input_forwarded: input_forwarded,
489
+ tab_action: filtered[:tab_action],
490
+ truncated: truncated
491
+ )
462
492
  end
463
493
  update_window_size
464
494
  end
@@ -512,8 +542,27 @@ module Kward
512
542
  buffer.bytesize - suffix_length
513
543
  end
514
544
 
545
+ # Idle job output must not fill the PTY and block background processes.
546
+ # Never compete with an active reader, including a tab-detached command
547
+ # whose protocol outlives execute_protocol's command mutex ownership.
548
+ def drain_idle_output
549
+ return false unless @command_mutex.try_lock
550
+
551
+ begin
552
+ return false if @protocol_pending || @closed
553
+
554
+ chunk = read_chunk
555
+ !chunk.nil? && chunk != :wait_readable
556
+ ensure
557
+ @command_mutex.unlock
558
+ end
559
+ rescue IOError, Errno::EIO
560
+ false
561
+ end
562
+
515
563
  def drain_prompt_output
516
- loop do
564
+ # A continuously writing job must not prevent returning to the prompt.
565
+ 16.times do
517
566
  readable = IO.select([@reader], nil, nil, 0.01)&.first || []
518
567
  break unless readable.include?(@reader)
519
568
 
@@ -574,7 +623,7 @@ module Kward
574
623
  output << "Exit status: #{status}\n" unless status.zero?
575
624
  update_cwd(protocol[:cwd])
576
625
  block&.call(output)
577
- Result.new(output: output, exit_status: status, streamed: block_given?)
626
+ Result.new(output: output, exit_status: status, streamed: block_given?, exit_shell: exited?)
578
627
  end
579
628
 
580
629
  def source_result(command, words)
@@ -584,19 +633,10 @@ module Kward
584
633
 
585
634
  path = Kwshrc.resolve_path(words[1], cwd: @cwd, env: @env)
586
635
  config = Kwshrc.read_file(path, env: @env)
587
- exports = config[:env]
588
- if exports.any?
589
- assignments = exports.map { |key, value| "#{key}=#{Shellwords.escape(value)}" }
590
- protocol = execute_protocol("export #{assignments.join(" ")}", timeout_seconds: STARTUP_TIMEOUT_SECONDS, max_output_bytes: nil)
591
- unless protocol[:status].to_i.zero?
592
- return Result.new(output: "#{command_echo(command)}kwsh: source: could not apply environment\n", exit_status: 1)
593
- end
636
+ protocol = execute_protocol(":", config: config, timeout_seconds: STARTUP_TIMEOUT_SECONDS, max_output_bytes: nil)
637
+ unless protocol[:status].to_i.zero?
638
+ return Result.new(output: "#{command_echo(command)}kwsh: source: could not apply configuration\n", exit_status: 1)
594
639
  end
595
-
596
- @env.merge!(exports)
597
- @aliases.merge!(config[:aliases])
598
- @routing_shell = build_routing_shell
599
- @completion_shell = nil
600
640
  Result.new(output: command_echo(command), exit_status: 0)
601
641
  rescue Kwshrc::ParseError => e
602
642
  Result.new(output: "#{command_echo(command)}kwsh: source: #{e.message}\n", exit_status: 1)
@@ -626,73 +666,25 @@ module Kward
626
666
  Result.new(output: command_echo(command), exit_status: 0, interactive_command: interactive_command)
627
667
  end
628
668
 
629
- def exit_result(command, words)
630
- if words.length > 2 || (words[1] && !words[1].match?(/\A\d+\z/))
631
- return Result.new(output: "#{command_echo(command)}kwsh: #{words.first}: numeric status expected\n", exit_status: 2)
632
- end
633
-
634
- Result.new(output: command_echo(command), exit_status: words[1].to_i, exit_shell: true)
635
- end
636
-
637
- def sync_runtime_state(words)
638
- changed = sync_runtime_aliases(words) || sync_runtime_environment(words)
639
- return unless changed
640
-
641
- @routing_shell = build_routing_shell
642
- @completion_shell = nil
643
- end
644
-
645
- def sync_runtime_aliases(words)
646
- case words.first
647
- when "alias"
648
- before = @aliases.dup
649
- words.drop(1).each do |assignment|
650
- name, value = assignment.split("=", 2)
651
- @aliases[name] = value.to_s if value && Kwsh.valid_alias_name?(name)
652
- end
653
- before != @aliases
654
- when "unalias"
655
- before = @aliases.dup
656
- if words == ["unalias", "-a"]
657
- @aliases.clear
658
- else
659
- words.drop(1).reject { |name| name.start_with?("-") }.each { |name| @aliases.delete(name) }
660
- end
661
- before != @aliases
662
- else
663
- false
664
- end
665
- end
666
-
667
- def sync_runtime_environment(words)
668
- before = @env.dup
669
- case words.first
670
- when "export"
671
- words.drop(1).reject { |assignment| assignment.start_with?("-") }.each do |assignment|
672
- key, value = assignment.split("=", 2)
673
- @env[key] = value.to_s if value && valid_environment_key?(key)
674
- end
675
- when "unset"
676
- words.drop(1).reject { |key| key == "--" || key.start_with?("-") }.each do |key|
677
- @env.delete(key) if valid_environment_key?(key)
678
- end
679
- else
680
- if words.all? { |word| word.match?(/\A[A-Za-z_][A-Za-z0-9_]*=.*/) }
681
- words.each do |assignment|
682
- key, value = assignment.split("=", 2)
683
- @env[key] = value.to_s if valid_environment_key?(key)
684
- end
685
- end
686
- end
687
- before != @env
688
- end
669
+ # Host-only conveniences apply only to a single simple command. Compound
670
+ # programs always belong to the interpreter, even when they start with cd.
671
+ def routing_words(command, tree)
672
+ return ["capture"] if command.match?(/\A\s*capture(?:\s|\z)/)
673
+ return ["pty"] if command.match?(/\A\s*pty(?:\s|\z)/)
674
+ commands = tree.values.first
675
+ return [] unless commands.length == 1 && commands.first.kind == :pipeline
676
+ stages, negate = commands.first.values
677
+ return [] if negate || stages.length != 1 || stages.first.kind != :simple
678
+ _, redirects = stages.first.values
679
+ return [] unless redirects.empty?
689
680
 
690
- def valid_environment_key?(key)
691
- key.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
681
+ shell_words(command)
682
+ rescue ArgumentError
683
+ []
692
684
  end
693
685
 
694
686
  def stateful_command?(words)
695
- STATEFUL_COMMANDS.include?(words.first) || words.all? { |word| word.match?(/\A[A-Za-z_][A-Za-z0-9_]*=.*/) }
687
+ STATEFUL_COMMANDS.include?(words.first) || words.any? && words.all? { |word| word.match?(/\A[A-Za-z_][A-Za-z0-9_]*=.*/) }
696
688
  end
697
689
 
698
690
  def shell_words(command)
@@ -803,8 +795,8 @@ module Kward
803
795
  size = [rows, columns]
804
796
  return if size == @window_size
805
797
 
806
- @window_size = size
807
798
  @reader.winsize = size
799
+ @window_size = size
808
800
  rescue StandardError
809
801
  nil
810
802
  end
@@ -819,10 +811,12 @@ module Kward
819
811
  def terminate_process_group(pid)
820
812
  return unless pid
821
813
 
822
- signal_process("TERM", -pid) || signal_process("TERM", pid)
814
+ # The private worker's shutdown signal cannot be overridden by script traps.
815
+ # It closes job groups before the bounded hard-kill fallback below.
816
+ signal_process("USR2", pid)
823
817
  deadline = Time.now + 0.2
824
818
  while Time.now < deadline
825
- return unless process_running?(pid)
819
+ break unless process_running?(pid)
826
820
 
827
821
  sleep 0.02
828
822
  end
@@ -14,6 +14,20 @@ module Kward
14
14
 
15
15
  Use run_shell_command when the user explicitly asks you to execute a command or change shell state, such as changing directory or setting an environment variable. That tool operates in the user's active shell session, so state changes persist.
16
16
 
17
+ The session uses native kwsh, not Bash or /bin/sh. Supported syntax includes quoting, variables and export, positional arguments, &&/||/!, pipelines, subshells, nested command substitution, heredocs and redirection on descriptors 0-9, if/elif/else, case patterns, loops, functions, return, and multilevel break/continue. Run native script files with kwsh <file> [arguments]. Executable text without a shebang is also interpreted natively after ENOEXEC, including through PATH and exec; permission failures and binary-looking files are rejected, never retried through another shell. Background jobs, wait, traps, exec, jobs, fg/bg, and kill are supported. Use $! to save a background PID and wait to collect its status. Job control is enabled in the hosted session; fg and terminal input belong to user-driven interactive commands, not autonomous agent execution. Hosted exec ends the shell session after its command finishes. Failed standalone interactive exec accepts a fresh submission; successful redirections remain in effect, while non-interactive exec failures exit. USR2 is reserved for hosted shutdown. trap -p includes defaults and supports saved=$(trap -p) followed by eval "$saved"; inherited ignored signals cannot be changed in non-interactive shells. Standalone interactive kwsh ignores TERM/QUIT and job-control stop signals by default; child commands reset shell-only defaults. Ruby-reserved ILL/FPE/BUS/SEGV/VTALRM actions remain unsupported. Full POSIX/Bash compatibility is not claimed. Do not work around this by invoking another shell unless the user explicitly requests that. The native source builtin is equivalent to . and executes a file in the current shell. At the hosted /shell prompt only, top-level source is a declarative config loader; use . ./file there to execute a script.
18
+
19
+ Indexed arrays use values=(one "two words"), values[index]=value, and "${values[@]}". Associative arrays use declare -A name=([key]=value), or separate declaration and assignment. array+=(...) appends elements; read -a array reads fields. [[ ... ]] supports quoted string/numeric/file tests, patterns, and lazy Boolean conditions; regex support is limited. Process substitution <(command) and >(command) is command-scoped: do not save its /dev/fd paths for later. Brace expansion supports choices and sequences. Enable recursive ** globbing explicitly with shopt -s globstar. Functions support dynamically scoped local name, local name=value, and local name=(...) for indexed arrays. Local associative arrays, namerefs, and array prefix environments are unsupported. Interactive kward shell supports the rbenv 1.3.2 completion subset: complete -F function command and compgen -W wordlist -- prefix, with literal COMP_WORDS/COMP_CWORD and COMPREPLY. Callbacks can run code when the user presses Tab; only register them for trusted functions on explicit request.
20
+
21
+ Use which name to report live shell resolution, including aliases. Options such as which -a use the external PATH utility. Native utilities include readonly, getopts, command, hash, type, times, eval, umask, ulimit, and set options -a/-b/-e/-f/-h/-m/-n/-u/-v/-x/-C plus pipefail. Builtin flags support -- and documented combinations; cd supports CDPATH and -P -e (status 1 means changed directory but unavailable physical pathname). umask supports -S/--, permission copies such as g=u, and sequential symbolic operations; setting a mask does not print it. ulimit supports -H/-S/-a and resources -c/-d/-f/-n/-s/-t/-v; -f and -c use 512-byte units, -d/-s/-v use 1024-byte units, and -t uses seconds. Queries default to the soft file-size limit; setting without -H/-S changes both limits. Prefer -S in an explicit subshell for temporary limits: hard-limit reductions can be irreversible. Limits affect the shell worker and its descendants, not the Kward host or other tabs; excessively low limits can terminate the session. Logical cd checks directory components before removing ..; execution, sourcing, redirections and globs retain directory identity across renames. PWD is logical; use pwd -P for the current physical pathname. eval explicitly executes native source and is not a way to make unsupported syntax work. set -x traces expanded values using parameter-expanded PS4, including assignment-only commands, so do not enable it around secrets. Command substitution inherits set -e. Fatal assignment, expansion, and direct special-builtin errors stop scripts even without set -e; interactive errors leave the session usable. Standalone kwsh inherits descriptors 3-9 for redirection and child commands; hosted sessions do not expose private host descriptors. Standalone kwsh supports file, -c, -s, and plain -i interactive execution with guarded ENV startup; this does not change the active session tool's ownership or sandbox rules. Native fc and HISTFILE/HISTSIZE/FCEDIT belong to standalone history, not the hosted composer; persistence is opt-in and can contain secrets. Standalone PS1 expands !/!! history numbers; ignoreeof protects interactive EOF, nolog is a compatible no-op, and MAIL/MAILPATH/MAILCHECK control prompt-time mail notifications. Standalone set -o vi provides native vi line editing and private external-vi edits; it is not the hosted composer and is unavailable through the active shell tool.
22
+
23
+ Interactive kward shell supports a single-line Zsh-style PROMPT template, for example export PROMPT='%F{cyan}%~%f [%?] %# '. When unset it falls back to PS1; PS2 still controls continuations. PROMPT is not evaluated as shell code, and it does not change the hosted /shell composer or the separate kwsh executable.
24
+
25
+ Native aliases expand unquoted command tokens at read time, including nested aliases and trailing-blank eligibility; quoted or expanded data never becomes an alias. Define an alias on a separate complete input line before using it. Aliases share the input lexer and can contain quote fragments or here-documents. Alias names may be numeric or contain !%,-@_; alias listings use quoted name=value entries without an alias prefix, unlike command descriptions. Script files execute incrementally. Tilde expansion supports named users and assignment-path components. LC_ALL, LC_CTYPE, LC_COLLATE, and LANG select installed libc locales for pattern classes, string ordering, glob sorting, and character counts; unavailable locales error explicitly. Multi-character collating elements such as [[.ch.]] work when defined by the installed locale, with bounded non-recursive matching. Redirection operands are not field-split or globbed; here-document continuations are removed before delimiter recognition.
26
+
27
+ Parameter expansion supports defaults (${name:-default}), assignment (${name:=default}), errors (${name:?message}), alternate values (${name:+word}), their colon-free forms, lengths (${#name}), and prefix/suffix pattern removal (#, ##, %, %%). Operands expand only when needed. read [-r] [-d delimiter] variable... and custom IFS are supported; use while IFS= read -r line || [ -n "$line" ]; do ...; done < file to retain an unterminated final line. Read input from a file or pipe for agent execution; prepare commands that need terminal input instead. case uses pattern alternatives separated by |; ;; stops matching and POSIX ;& falls through without testing the next pattern. New invocations reset IFS to space/tab/newline, initialize PPID to the parent process ID, and reset OPTIND to 1; subshells retain these values. Standalone startup preserves valid inherited logical PWD, while hosted sessions retain their explicit workspace root. Standalone $0 follows the invocation, command file, or explicit -c command name; a leading - operand is ignored before selecting file, stdin, or command-string operands. LINENO tracks script and function source lines until explicitly assigned or unset.
28
+
29
+ Integer arithmetic expansion is supported: echo $((5 + 2)) prints 7. Use adjacent closing parentheses for portable syntax; kwsh also accepts spaces or tabs between the closing parentheses, so echo $((5 + 2) ) works too. Arithmetic includes comparisons, logical/bitwise operators, shifts, assignments, ++/--, exponentiation, and lazy conditionals. ((expression)) returns success for nonzero results; for ((init; condition; update)) supports counter loops. Arithmetic has no fixed expression-byte limit; long flat binary chains are iterative. Integer bit_length is limited to 4096 and recursive parsing/evaluation to 100 levels, not Bash machine-integer overflow. Other parser, alias, capture, pattern, glob, and job safety quotas still apply to standalone and hosted execution; they remain explicit POSIX conformance gaps. Arithmetic expansion supports nested parameter, command, and arithmetic substitutions, expanded once before integer evaluation. Arithmetic array references and substitutions in Bash-style ((...)) command/loop forms remain unsupported.
30
+
17
31
  Use prepare_shell_command when the user asks you to suggest or prepare a command. It places the complete command in the shell prompt but does not execute it; the user must press Enter. Never claim that a prepared command was executed.
18
32
 
19
33
  When available, use open_editor if the user explicitly asks to open an existing workspace file in Kward's integrated editor. Opening the editor does not modify or save the file.