kward 0.82.0 → 0.84.0

data/lib/kward/editor_prompt.rb

@@ -0,0 +1,46 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Builds the model-facing request for an in-memory editor prompt.
+  module EditorPrompt
+    module_function
+
+    def system_message
+      {
+        role: "system",
+        content: <<~PROMPT.strip
+          You are Kward's in-memory editor assistant.
+
+          Act only on the user's explicit request about the active editor buffer. Do not volunteer changes, explanations, or unrelated work. For an actionable edit request, call replace_editor_buffer with the complete replacement buffer. For a request that is only a question or needs clarification, answer briefly without changing the buffer. Never write files to disk and never claim that the buffer was saved.
+        PROMPT
+      }
+    end
+
+    def input(instruction, context)
+      document = context[:display_path].to_s
+      language = context[:language].to_s
+      language = "text" if language.empty?
+      content = context[:content].to_s
+
+      <<~PROMPT
+        You are operating inside an interactive editor.
+
+        The user requested:
+        #{instruction}
+
+        Active document: #{document.empty? ? "(untitled)" : document}
+        Language: #{language}
+        Cursor: line #{context.dig(:cursor, 0).to_i + 1}, column #{context.dig(:cursor, 1).to_i + 1}
+        Selected text: #{context[:selection].to_s.empty? ? "(none)" : "present; full-buffer replacement is required"}
+
+        Current buffer:
+        <editor_buffer>
+        #{content}
+        </editor_buffer>
+
+        Satisfy the user's request by calling replace_editor_buffer with the complete desired buffer contents.
+        The operation changes only the in-memory editor buffer. Do not write files to disk.
+        If the request is ambiguous, explain the ambiguity instead of changing the buffer.
+      PROMPT
+    end
+  end
+end

data/lib/kward/editor_prompt_session.rb

@@ -0,0 +1,28 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Transactional draft used while an agent works on an active editor buffer.
+  #
+  # The live terminal editor remains owned by PromptInterface. Agent tool calls
+  # update this draft and the caller commits it only after a successful turn.
+  class EditorPromptSession
+    attr_reader :context, :content
+
+    def initialize(context)
+      @context = context.dup
+      @initial_content = @context.fetch(:content).to_s.dup
+      @content = @initial_content.dup
+    end
+
+    def replace(content)
+      @content = content.to_s
+    end
+
+    def changed?
+      @content != @initial_content
+    end
+
+    def initial_content
+      @initial_content.dup
+    end
+  end
+end

data/lib/kward/interactive_pty_runner.rb

@@ -3,6 +3,7 @@ require "pty"
 require "timeout"
 require_relative "local_pty_command_runner"
 require_relative "pty_output_sink"
+require_relative "detached_run"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -10,7 +11,7 @@ module Kward
   # This is intentionally low level: UI orchestration decides when terminal
   # ownership is handed to the child process and how the result is presented.
   class InteractivePtyRunner
-    Result = Struct.new(:exit_status, :input_forwarded, keyword_init: true)
+    Result = Struct.new(:exit_status, :input_forwarded, :tab_action, :background, keyword_init: true)
 
     READ_SIZE = 4096
 
@@ -19,28 +20,43 @@ module Kward
       @window_size = nil
     end
 
-    def run(*command, env: {}, cwd: Dir.pwd, input: $stdin, sink:)
-      pid = nil
+    def run(*command, env: {}, cwd: Dir.pwd, input: $stdin, sink:, tab_action_handler: nil, on_detach: nil)
+      reader, writer, pid = PTY.spawn(env.to_h, *command, chdir: cwd.to_s)
       status = nil
-      writer = nil
       input_forwarded = false
-
-      PTY.spawn(env.to_h, *command, chdir: cwd.to_s) do |reader, child_writer, child_pid|
-        pid = child_pid
-        writer = child_writer
-        update_window_size(reader, pid)
-        with_raw_input(input) do
-          input_forwarded = drain_initial_input(input, writer, sink)
-          status, forwarded = forward_io(reader, writer, pid, input, sink)
+      tab_action = nil
+      forwarded = false
+      detached = nil
+
+      update_window_size(reader, pid)
+      with_raw_input(input) do
+        input_forwarded, tab_action = drain_initial_input(input, writer, sink, tab_action_handler: tab_action_handler)
+        if tab_action && on_detach
+          detached_sink = on_detach.call
+          sink.finish if sink.respond_to?(:finish)
+          detached = detach_process(reader, writer, pid, detached_sink, input_forwarded)
+          reader = writer = pid = nil
+        elsif tab_action
+          status = terminate_and_reap(pid)
+        else
+          status, forwarded, tab_action = forward_io(reader, writer, pid, input, sink, tab_action_handler: tab_action_handler, on_detach: on_detach)
           input_forwarded ||= forwarded
+          if tab_action && on_detach
+            detached_sink = on_detach.call
+            sink.finish if sink.respond_to?(:finish)
+            detached = detach_process(reader, writer, pid, detached_sink, input_forwarded)
+            reader = writer = pid = nil
+          end
         end
-        sink.finish if sink.respond_to?(:finish)
-        status ||= wait_for_status(pid)
+        input_forwarded ||= forwarded
       end
+      sink.finish if sink.respond_to?(:finish) && !detached
+      status ||= wait_for_status(pid) if pid
 
-      Result.new(exit_status: exit_status(status), input_forwarded: input_forwarded)
+      Result.new(exit_status: exit_status(status), input_forwarded: input_forwarded, tab_action: tab_action, background: detached)
     ensure
       writer&.close unless writer&.closed?
+      reader&.close unless reader&.closed?
       terminate_and_reap(pid) if pid && status.nil?
     end
 
@@ -60,23 +76,39 @@ module Kward
       yield
     end
 
-    def drain_initial_input(input, writer, sink)
+    def drain_initial_input(input, writer, sink, tab_action_handler: nil)
       forwarded = false
       loop do
         chunk = input.read_nonblock(READ_SIZE, exception: false)
         break if chunk.nil? || chunk == :wait_readable
 
+        filtered = tab_action_handler&.call(chunk)
+        if filtered
+          tab_action = filtered[:tab_action]
+          chunk = filtered[:input].to_s
+          if tab_action
+            unless chunk.empty?
+              sink.input_forwarded if sink.respond_to?(:input_forwarded)
+              writer.write(chunk)
+              writer.flush
+              forwarded = true
+            end
+            return [forwarded, tab_action]
+          end
+        end
+        next if chunk.empty?
+
         sink.input_forwarded if sink.respond_to?(:input_forwarded)
         writer.write(chunk)
         forwarded = true
       end
       writer.flush
-      forwarded
+      [forwarded, nil]
     rescue Errno::EIO, Errno::EPIPE, IOError
-      forwarded
+      [forwarded, nil]
     end
 
-    def forward_io(reader, writer, pid, input, sink)
+    def forward_io(reader, writer, pid, input, sink, tab_action_handler: nil, on_detach: nil)
       input_open = true
       input_forwarded = false
       loop do
@@ -86,19 +118,45 @@ module Kward
         readable = IO.select(readers, nil, nil, 0.02)&.first || []
         forward_pty_output(reader, sink) if readable.include?(reader)
         if input_open && readable.include?(input)
-          input_open, forwarded = forward_input(input, writer, sink)
+          input_open, forwarded, tab_action = forward_input(input, writer, sink, tab_action_handler: tab_action_handler)
           input_forwarded ||= forwarded
+          return [nil, input_forwarded, tab_action] if tab_action && on_detach
+          return [terminate_and_reap(pid), input_forwarded, tab_action] if tab_action
         end
 
         status = finished_status(pid)
         next unless status
 
-        return [finish_stopped_process(pid), input_forwarded] if status.stopped?
+        return [finish_stopped_process(pid), input_forwarded, nil] if status.stopped?
 
         drain_pty_output(reader, sink)
-        return [status, input_forwarded]
+        return [status, input_forwarded, nil]
       rescue Errno::EIO
-        return [wait_for_status(pid), input_forwarded]
+        return [wait_for_status(pid), input_forwarded, nil]
+      end
+    end
+
+    def detach_process(reader, writer, pid, sink, input_forwarded)
+      DetachedRun.new(sink: sink, canceler: -> { terminate_process_group(pid) }) do
+        status = nil
+        begin
+          loop do
+            readable, = IO.select([reader], nil, nil, 0.02)&.first
+            forward_pty_output(reader, sink) if readable
+            status = finished_status(pid)
+            next unless status
+
+            drain_pty_output(reader, sink)
+            break
+          end
+        rescue Errno::EIO
+          status = wait_for_status(pid)
+        ensure
+          sink.finish if sink.respond_to?(:finish)
+          writer.close unless writer.closed?
+          reader.close unless reader.closed?
+        end
+        Result.new(exit_status: exit_status(status), input_forwarded: input_forwarded)
       end
     end
 
@@ -125,17 +183,33 @@ module Kward
       nil
     end
 
-    def forward_input(input, writer, sink)
+    def forward_input(input, writer, sink, tab_action_handler: nil)
       chunk = input.read_nonblock(READ_SIZE, exception: false)
-      return [false, false] if chunk.nil?
-      return [true, false] if chunk == :wait_readable
+      return [false, false, nil] if chunk.nil?
+      return [true, false, nil] if chunk == :wait_readable
+
+      filtered = tab_action_handler&.call(chunk)
+      if filtered
+        tab_action = filtered[:tab_action]
+        chunk = filtered[:input].to_s
+        if tab_action
+          unless chunk.empty?
+            sink.input_forwarded if sink.respond_to?(:input_forwarded)
+            writer.write(chunk)
+            writer.flush
+            return [true, true, tab_action]
+          end
+          return [true, false, tab_action]
+        end
+      end
+      return [true, false, nil] if chunk.empty?
 
       sink.input_forwarded if sink.respond_to?(:input_forwarded)
       writer.write(chunk)
       writer.flush
-      [true, true]
+      [true, true, nil]
     rescue Errno::EIO, Errno::EPIPE, IOError
-      [false, false]
+      [false, false, nil]
     end
 
     def update_window_size(reader, pid)

data/lib/kward/{ekwsh.rb → kwsh.rb}

@@ -10,25 +10,24 @@ end
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Kward-native embedded shell command runner.
-  class Ekwsh
+  class Kwsh
     Result = Struct.new(:output, :exit_status, :exit_shell, :clear, :open_editor_path, :interactive_command, :streamed, keyword_init: true)
     Completion = Struct.new(:range, :replacement, :candidates, keyword_init: true)
-    BUILTINS = %w[alias capture cd pwd export unset unalias clear exit logout pty].freeze
+    BUILTINS = %w[alias capture cd pwd export source unset unalias clear exit logout pty].freeze
     DEFAULT_SHELL = "/bin/sh"
     DEFAULT_TIMEOUT_SECONDS = 300
     DEFAULT_MAX_OUTPUT_BYTES = 1_048_576
     DEFAULT_HISTORY_LIMIT = 1_000
+    CONTEXT_OUTPUT_BYTES = 32_000
 
-    attr_reader :cwd
+    attr_reader :cwd, :last_command, :timeout_seconds
 
     def command_shell
       @shell
     end
 
     def child_env(interactive: false)
-      env = @env.dup
-      env.delete("GIT_PAGER") if interactive && @defaulted_git_pager
-      env
+      @env.dup
     end
 
     def initialize(cwd: Dir.pwd, env: ENV.to_h, shell: DEFAULT_SHELL, configured_env: {}, aliases: {}, timeout_seconds: DEFAULT_TIMEOUT_SECONDS, max_output_bytes: DEFAULT_MAX_OUTPUT_BYTES)
@@ -43,6 +42,8 @@ module Kward
       @shell = shell.to_s.empty? ? DEFAULT_SHELL : shell.to_s
       @timeout_seconds = timeout_seconds.to_i.positive? ? timeout_seconds.to_i : DEFAULT_TIMEOUT_SECONDS
       @max_output_bytes = max_output_bytes.to_i.positive? ? max_output_bytes.to_i : DEFAULT_MAX_OUTPUT_BYTES
+      @last_command = nil
+      @last_result = nil
     end
 
     def prompt_label
@@ -53,7 +54,45 @@ module Kward
       command = input.to_s.strip
       return Result.new(output: "", exit_status: 0) if command.empty?
 
-      run_expanded_command(command, cancellation: cancellation, &block)
+      result = run_expanded_command(command, cancellation: cancellation, &block)
+      remember_result(command, result)
+      result
+    end
+
+    # Runs a command for the shell assistant without handing it the terminal.
+    # Built-ins still execute in this Kwsh instance so their state persists.
+    def run_for_agent(input, timeout_seconds: nil, cancellation: nil)
+      command = input.to_s.strip
+      return run(command, cancellation: cancellation) if command.empty?
+
+      result = run(command, cancellation: cancellation)
+      return result unless result.interactive_command
+
+      result = execute(
+        result.interactive_command,
+        display_command: command,
+        timeout_seconds: timeout_seconds,
+        cancellation: cancellation
+      )
+      remember_result(command, result)
+      result
+    end
+
+    # Records the output of an interactive command after terminal handoff.
+    def record_interactive_result(output:, exit_status:)
+      return unless @last_command
+
+      @last_result = Result.new(output: ANSI.sanitize_transcript(output.to_s), exit_status: exit_status)
+    end
+
+    # Returns bounded shell state for an explicit shell-agent prompt.
+    def context_snapshot(max_output_bytes: CONTEXT_OUTPUT_BYTES)
+      {
+        cwd: @cwd,
+        last_command: @last_command,
+        exit_status: @last_result&.exit_status,
+        last_output: context_output(@last_result&.output, max_output_bytes)
+      }
     end
 
     def complete(input, cursor)
@@ -112,8 +151,6 @@ module Kward
     def configure_color_environment
       @env["CLICOLOR"] ||= "1"
       @env["COLORTERM"] ||= "truecolor"
-      @defaulted_git_pager = !@env.key?("GIT_PAGER")
-      @env["GIT_PAGER"] ||= "cat"
       @env["TERM"] = "xterm-256color" if @env["TERM"].to_s.empty? || @env["TERM"] == "dumb"
     end
 
@@ -285,12 +322,12 @@ module Kward
       return nil unless %w[exit logout].include?(words.first)
 
       if words.length > 2 || (words[1] && !words[1].match?(/\A\d+\z/))
-        return Result.new(output: "#{command_echo(display_command)}ekwsh: #{words.first}: numeric status expected\n", exit_status: 2)
+        return Result.new(output: "#{command_echo(display_command)}kwsh: #{words.first}: numeric status expected\n", exit_status: 2)
       end
 
       Result.new(output: command_echo(display_command), exit_status: words[1].to_i, exit_shell: true)
     rescue ArgumentError => e
-      Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 2)
+      Result.new(output: "#{command_echo(display_command)}kwsh: #{e.message}\n", exit_status: 2)
     end
 
     def builtin_result(command, display_command: command, cancellation: nil, &block)
@@ -310,6 +347,8 @@ module Kward
         print_working_directory(display_command, words)
       when "export"
         export_variables(display_command, words)
+      when "source", "."
+        source_file(display_command, words)
       when "unset"
         unset_variables(display_command, words)
       when "clear"
@@ -322,7 +361,7 @@ module Kward
         nil
       end
     rescue ArgumentError => e
-      Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 2)
+      Result.new(output: "#{command_echo(display_command)}kwsh: #{e.message}\n", exit_status: 2)
     end
 
     def captured_command_result(command, display_command:, cancellation: nil, &block)
@@ -362,7 +401,7 @@ module Kward
           invalid << name
         end
       end
-      return Result.new(output: "#{command_echo(command)}ekwsh: alias: invalid name: #{invalid.join(" ")}\n", exit_status: 2) unless invalid.empty?
+      return Result.new(output: "#{command_echo(command)}kwsh: alias: invalid name: #{invalid.join(" ")}\n", exit_status: 2) unless invalid.empty?
 
       names = @aliases.keys.sort if names.empty? && assignments.empty?
       lines = names.filter_map { |name| @aliases[name] ? "alias #{name}=#{Shellwords.escape(@aliases.fetch(name))}" : nil }
@@ -380,7 +419,7 @@ module Kward
       end
 
       missing = words.drop(1).reject { |name| @aliases.delete(name) }
-      return Result.new(output: "#{command_echo(command)}ekwsh: unalias: not found: #{missing.join(" ")}\n", exit_status: 1) unless missing.empty?
+      return Result.new(output: "#{command_echo(command)}kwsh: unalias: not found: #{missing.join(" ")}\n", exit_status: 1) unless missing.empty?
 
       Result.new(output: command_echo(command), exit_status: 0)
     end
@@ -418,7 +457,7 @@ module Kward
       path = File.expand_path(words[2], @cwd)
       Result.new(output: command_echo(display_command), exit_status: 0, open_editor_path: path)
     rescue ArgumentError => e
-      Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 2)
+      Result.new(output: "#{command_echo(display_command)}kwsh: #{e.message}\n", exit_status: 2)
     end
 
     def kward_edit_command?(words)
@@ -452,7 +491,7 @@ module Kward
 
     def change_directory(command, words)
       if words.length > 2
-        return Result.new(output: "#{command_echo(command)}ekwsh: cd: too many arguments\n", exit_status: 2)
+        return Result.new(output: "#{command_echo(command)}kwsh: cd: too many arguments\n", exit_status: 2)
       end
 
       target = words[1]
@@ -460,7 +499,7 @@ module Kward
       target = @previous_cwd || @cwd if target == "-"
       path = File.expand_path(target, @cwd)
       unless File.directory?(path)
-        return Result.new(output: "#{command_echo(command)}ekwsh: cd: no such directory: #{target}\n", exit_status: 1)
+        return Result.new(output: "#{command_echo(command)}kwsh: cd: no such directory: #{target}\n", exit_status: 1)
       end
 
       @previous_cwd = @cwd
@@ -491,8 +530,25 @@ module Kward
       if invalid.empty?
         Result.new(output: command_echo(command), exit_status: 0)
       else
-        Result.new(output: "#{command_echo(command)}ekwsh: export: invalid assignment: #{invalid.join(" ")}\n", exit_status: 2)
+        Result.new(output: "#{command_echo(command)}kwsh: export: invalid assignment: #{invalid.join(" ")}\n", exit_status: 2)
+      end
+    end
+
+    def source_file(command, words)
+      unless words.length == 2
+        return Result.new(output: "#{command_echo(command)}Usage: source <file>\n", exit_status: 2)
       end
+
+      require_relative "kwshrc"
+      path = Kwshrc.resolve_path(words[1], cwd: @cwd, env: @env)
+      config = Kwshrc.read_file(path, env: @env)
+      path_changed = config[:env].key?("PATH")
+      @env.merge!(config[:env])
+      @aliases.merge!(config[:aliases])
+      invalidate_path_executables_cache if path_changed
+      Result.new(output: command_echo(command), exit_status: 0)
+    rescue Kwshrc::ParseError => e
+      Result.new(output: "#{command_echo(command)}kwsh: source: #{e.message}\n", exit_status: 1)
     end
 
     def unset_variables(command, words)
@@ -504,7 +560,7 @@ module Kward
       if invalid.empty?
         Result.new(output: command_echo(command), exit_status: 0)
       else
-        Result.new(output: "#{command_echo(command)}ekwsh: unset: invalid name: #{invalid.join(" ")}\n", exit_status: 2)
+        Result.new(output: "#{command_echo(command)}kwsh: unset: invalid name: #{invalid.join(" ")}\n", exit_status: 2)
       end
     end
 
@@ -522,12 +578,13 @@ module Kward
       key.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
     end
 
-    def execute(command, display_command: command, cancellation: nil)
+    def execute(command, display_command: command, timeout_seconds: nil, cancellation: nil)
       output = command_echo(display_command)
       streamed = block_given?
       yield output.dup if streamed
+      timeout = effective_timeout(timeout_seconds)
       result = external_command_runner.new(
-        timeout_seconds: @timeout_seconds,
+        timeout_seconds: timeout,
         max_output_bytes: @max_output_bytes,
         terminate_on_output_limit: true
       ).run(@shell, "-c", command, env: @env, cwd: @cwd, cancellation: cancellation) do |_stream, chunk|
@@ -537,8 +594,8 @@ module Kward
       end
       append_output_newline(output) { |text| yield text if streamed }
       exit_status = result.timed_out || result.truncated ? 1 : (result.exit_status || 1)
-      append_streamed(output, "ekwsh: command timed out after #{@timeout_seconds} seconds\n", streamed) { |text| yield text } if result.timed_out
-      append_streamed(output, "ekwsh: output exceeded #{@max_output_bytes} bytes; command terminated\n", streamed) { |text| yield text } if result.truncated
+      append_streamed(output, "kwsh: command timed out after #{timeout} seconds\n", streamed) { |text| yield text } if result.timed_out
+      append_streamed(output, "kwsh: output exceeded #{@max_output_bytes} bytes; command terminated\n", streamed) { |text| yield text } if result.truncated
       append_streamed(output, "Exit status: #{exit_status}\n", streamed) { |text| yield text } unless exit_status.zero?
       Result.new(output: output, exit_status: exit_status, streamed: streamed)
     rescue Cancellation::CancelledError
@@ -546,7 +603,29 @@ module Kward
       append_streamed(output, "^C\nExit status: 130\n", streamed) { |text| yield text }
       Result.new(output: output, exit_status: 130, streamed: streamed)
     rescue Errno::ENOENT => e
-      Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 127)
+      Result.new(output: "#{command_echo(display_command)}kwsh: #{e.message}\n", exit_status: 127)
+    end
+
+    def effective_timeout(timeout_seconds)
+      timeout = timeout_seconds.to_i
+      timeout.positive? ? timeout : @timeout_seconds
+    end
+
+    def remember_result(command, result)
+      @last_command = command.to_s
+      @last_result = result
+    end
+
+    def context_output(output, max_output_bytes)
+      text = ANSI.sanitize_transcript(output.to_s)
+      limit = max_output_bytes.to_i
+      return text if limit <= 0 || text.bytesize <= limit
+
+      prefix = "[Earlier output omitted; showing the end of the command output.]\n"
+      tail_limit = [limit - prefix.bytesize, 0].max
+      tail = text.byteslice(-tail_limit, tail_limit).to_s if tail_limit.positive?
+      value = "#{prefix}#{tail}"
+      ANSI.normalize_transcript_encoding(value.byteslice(-limit, limit).to_s)
     end
 
     def external_command_runner