kward 0.71.0 → 0.73.0

data/lib/kward/interactive_pty_runner.rb

@@ -0,0 +1,151 @@
+require "io/console"
+require "pty"
+require "timeout"
+require_relative "local_pty_command_runner"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Runs a command in a PTY while forwarding caller-owned input and output IOs.
+  # 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, keyword_init: true)
+
+    READ_SIZE = 4096
+
+    def initialize(window_size_provider: nil)
+      @window_size_provider = window_size_provider
+      @window_size = nil
+    end
+
+    def run(*command, env: {}, cwd: Dir.pwd, input: $stdin, output: $stdout)
+      pid = nil
+      status = nil
+
+      PTY.spawn(env.to_h, *command, chdir: cwd.to_s) do |reader, writer, child_pid|
+        pid = child_pid
+        update_window_size(reader, pid)
+        with_raw_input(input) do
+          drain_initial_input(input, writer)
+          loop do
+            update_window_size(reader, pid)
+            readable = IO.select([reader, input], nil, nil, 0.02)&.first || []
+            forward_pty_output(reader, output) if readable.include?(reader)
+            forward_input(input, writer) if readable.include?(input)
+            if (finished_status = finished_status(pid))
+              status = finished_status
+              break
+            end
+          rescue Errno::EIO, IOError
+            break
+          end
+        end
+        status ||= wait_for_status(pid)
+      ensure
+        writer&.close unless writer&.closed?
+      end
+
+      Result.new(exit_status: exit_status(status))
+    end
+
+    private
+
+    def with_raw_input(input)
+      return yield unless input.respond_to?(:raw)
+
+      input.raw { yield }
+    rescue Errno::ENOTTY
+      yield
+    end
+
+    def drain_initial_input(input, writer)
+      loop do
+        chunk = input.read_nonblock(READ_SIZE, exception: false)
+        break if chunk.nil? || chunk == :wait_readable
+
+        writer.write(chunk)
+      end
+      writer.flush
+    rescue Errno::EIO, Errno::EPIPE, IOError
+      nil
+    end
+
+    def forward_pty_output(reader, output)
+      chunk = reader.read_nonblock(READ_SIZE, exception: false)
+      return if chunk.nil? || chunk == :wait_readable
+
+      output.write(chunk)
+      output.flush if output.respond_to?(:flush)
+    end
+
+    def forward_input(input, writer)
+      chunk = input.read_nonblock(READ_SIZE, exception: false)
+      return if chunk.nil? || chunk == :wait_readable
+
+      writer.write(chunk)
+      writer.flush
+    rescue Errno::EIO, Errno::EPIPE, IOError
+      nil
+    end
+
+    def update_window_size(reader, pid)
+      window_size = terminal_window_size
+      return if window_size == @window_size
+
+      @window_size = window_size
+      reader.winsize = window_size
+      signal_process("WINCH", -pid) || signal_process("WINCH", pid)
+    rescue StandardError
+      nil
+    end
+
+    def terminal_window_size
+      rows, columns = @window_size_provider ? @window_size_provider.call : IO.console&.winsize
+      rows = LocalPtyCommandRunner::DEFAULT_ROWS unless rows.to_i.positive?
+      columns = LocalPtyCommandRunner::DEFAULT_COLUMNS unless columns.to_i.positive?
+      [rows, columns]
+    rescue StandardError
+      [LocalPtyCommandRunner::DEFAULT_ROWS, LocalPtyCommandRunner::DEFAULT_COLUMNS]
+    end
+
+    def finished_status(pid)
+      return unless pid
+
+      finished_pid, status = Process.wait2(pid, Process::WNOHANG)
+      status if finished_pid
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def wait_for_status(pid)
+      return unless pid
+
+      _, status = Process.wait2(pid)
+      status
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def exit_status(status)
+      return 1 unless status
+      return status.exitstatus if status.exited?
+      return 128 + status.termsig if status.signaled?
+
+      1
+    end
+
+    def process_running?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def signal_process(signal, pid)
+      Process.kill(signal, pid)
+      true
+    rescue Errno::ESRCH, Errno::EINVAL, Errno::EPERM
+      false
+    end
+  end
+end

data/lib/kward/local_command_runner.rb

@@ -0,0 +1,155 @@
+require "open3"
+require "thread"
+require "timeout"
+require_relative "cancellation"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Low-level local process runner with bounded capture, timeout, cancellation,
+  # and optional output streaming. Callers own command semantics and formatting.
+  class LocalCommandRunner
+    Result = Struct.new(:stdout, :stderr, :exit_status, :timed_out, :truncated, keyword_init: true)
+
+    READ_SIZE = 4096
+
+    def initialize(timeout_seconds:, max_output_bytes:, terminate_on_output_limit: false)
+      @timeout_seconds = timeout_seconds.to_i.positive? ? timeout_seconds.to_i : 30
+      @max_output_bytes = max_output_bytes.to_i.positive? ? max_output_bytes.to_i : 128 * 1024
+      @terminate_on_output_limit = terminate_on_output_limit
+    end
+
+    def run(*command, env: {}, cwd: Dir.pwd, cancellation: nil, &block)
+      cancellation&.raise_if_cancelled!
+      stdout_buffer = +""
+      stderr_buffer = +""
+      captured_bytes = 0
+      truncated = false
+      timed_out = false
+      queue = Queue.new
+
+      Open3.popen3(env.to_h, *command, chdir: cwd.to_s, pgroup: true) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        readers = [
+          read_stream(stdout, :stdout, queue),
+          read_stream(stderr, :stderr, queue)
+        ]
+        cancellation&.on_cancel { terminate_process_group(wait_thread.pid) }
+
+        status = wait_for_process(wait_thread, readers, queue, cancellation: cancellation) do |stream, chunk|
+          captured_bytes, truncated, captured_chunk = capture_chunk(
+            stream,
+            chunk,
+            stdout_buffer,
+            stderr_buffer,
+            captured_bytes,
+            truncated
+          )
+          block&.call(stream, captured_chunk) unless captured_chunk.empty?
+          terminate_process_group(wait_thread.pid) if truncated && @terminate_on_output_limit
+        end
+
+        join_readers(readers)
+        drain_queue(queue) do |stream, chunk|
+          captured_bytes, truncated, captured_chunk = capture_chunk(
+            stream,
+            chunk,
+            stdout_buffer,
+            stderr_buffer,
+            captured_bytes,
+            truncated
+          )
+          block&.call(stream, captured_chunk) unless captured_chunk.empty?
+        end
+
+        Result.new(stdout: stdout_buffer, stderr: stderr_buffer, exit_status: status.exitstatus || 1, timed_out: false, truncated: truncated)
+      rescue Timeout::Error
+        timed_out = true
+        terminate_process_group(wait_thread.pid)
+        join_readers(readers)
+        Result.new(stdout: stdout_buffer, stderr: stderr_buffer, exit_status: nil, timed_out: timed_out, truncated: truncated)
+      ensure
+        readers&.each { |reader| reader.kill if reader&.alive? }
+      end
+    end
+
+    private
+
+    def read_stream(io, stream, queue)
+      Thread.new do
+        loop do
+          queue << [stream, io.readpartial(READ_SIZE)]
+        rescue EOFError
+          break
+        end
+      end
+    end
+
+    def wait_for_process(wait_thread, readers, queue, cancellation:)
+      deadline = Time.now + @timeout_seconds
+      loop do
+        cancellation&.raise_if_cancelled!
+        drain_queue(queue) { |stream, chunk| yield(stream, chunk) }
+        if wait_thread.join(0.02)
+          cancellation&.raise_if_cancelled!
+          return wait_thread.value
+        end
+        raise Timeout::Error if Time.now >= deadline
+      end
+    rescue Cancellation::CancelledError
+      terminate_process_group(wait_thread.pid)
+      join_readers(readers)
+      raise
+    end
+
+    def drain_queue(queue)
+      loop do
+        stream, chunk = queue.pop(true)
+        yield(stream, chunk)
+      rescue ThreadError
+        break
+      end
+    end
+
+    def capture_chunk(stream, chunk, stdout_buffer, stderr_buffer, captured_bytes, truncated)
+      return [captured_bytes, truncated, ""] if truncated
+
+      remaining = @max_output_bytes - captured_bytes
+      if chunk.bytesize > remaining
+        truncated = true
+        chunk = remaining.positive? ? chunk.byteslice(0, remaining).to_s : ""
+      end
+
+      stream == :stderr ? stderr_buffer << chunk : stdout_buffer << chunk
+      [captured_bytes + chunk.bytesize, truncated, chunk]
+    end
+
+    def join_readers(readers)
+      readers.to_a.each { |reader| reader.join(0.1) }
+    end
+
+    def terminate_process_group(pid)
+      signal_process("TERM", -pid) || signal_process("TERM", pid)
+      deadline = Time.now + 0.2
+      while Time.now < deadline
+        return unless process_running?(pid)
+
+        sleep 0.02
+      end
+      signal_process("KILL", -pid) || signal_process("KILL", pid)
+    end
+
+    def process_running?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def signal_process(signal, pid)
+      Process.kill(signal, pid)
+      true
+    rescue Errno::ESRCH, Errno::EINVAL, Errno::EPERM
+      false
+    end
+  end
+end

data/lib/kward/local_pty_command_runner.rb

@@ -0,0 +1,171 @@
+require "io/console"
+require "pty"
+require "timeout"
+require_relative "cancellation"
+require_relative "local_command_runner"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Low-level pseudo-terminal command runner with bounded capture, timeout,
+  # cancellation, and optional output streaming. This gives child processes a
+  # TTY without trying to emulate an interactive terminal.
+  class LocalPtyCommandRunner
+    Result = LocalCommandRunner::Result
+
+    READ_SIZE = 4096
+    DEFAULT_ROWS = 24
+    DEFAULT_COLUMNS = 80
+
+    def initialize(timeout_seconds:, max_output_bytes:, terminate_on_output_limit: false, window_size_provider: nil)
+      @timeout_seconds = timeout_seconds.to_i.positive? ? timeout_seconds.to_i : 30
+      @max_output_bytes = max_output_bytes.to_i.positive? ? max_output_bytes.to_i : 128 * 1024
+      @terminate_on_output_limit = terminate_on_output_limit
+      @window_size_provider = window_size_provider
+      @window_size = nil
+    end
+
+    def run(*command, env: {}, cwd: Dir.pwd, cancellation: nil, &block)
+      cancellation&.raise_if_cancelled!
+      output = +""
+      captured_bytes = 0
+      truncated = false
+      timed_out = false
+      cancelled = false
+      pid = nil
+      status = nil
+
+      PTY.spawn(env.to_h, *command, chdir: cwd.to_s) do |reader, _writer, child_pid|
+        pid = child_pid
+        update_window_size(reader, pid)
+        cancellation&.on_cancel do
+          cancelled = true
+          terminate_process_group(pid)
+        end
+
+        begin
+          deadline = Time.now + @timeout_seconds
+          loop do
+            cancellation&.raise_if_cancelled!
+            raise Timeout::Error if Time.now >= deadline
+
+            update_window_size(reader, pid)
+            readable, = IO.select([reader], nil, nil, 0.02)
+            next unless readable
+
+            chunk = read_chunk(reader)
+            break if chunk.nil?
+
+            chunk = normalize_line_endings(chunk)
+            captured_bytes, truncated, captured_chunk = capture_chunk(chunk, output, captured_bytes, truncated)
+            block&.call(:stdout, captured_chunk) unless captured_chunk.empty?
+            terminate_process_group(pid) if truncated && @terminate_on_output_limit
+          end
+        rescue Errno::EIO
+          nil
+        end
+
+        status = wait_for_status(pid)
+      end
+
+      cancellation&.raise_if_cancelled! if cancelled
+      Result.new(stdout: output, stderr: "", exit_status: exit_status(status), timed_out: false, truncated: truncated)
+    rescue Timeout::Error
+      timed_out = true
+      terminate_process_group(pid) if pid
+      wait_for_status(pid) if pid
+      Result.new(stdout: output, stderr: "", exit_status: nil, timed_out: timed_out, truncated: truncated)
+    rescue Cancellation::CancelledError
+      terminate_process_group(pid) if pid
+      wait_for_status(pid) if pid
+      raise
+    end
+
+    private
+
+    def update_window_size(reader, pid)
+      window_size = terminal_window_size
+      return if window_size == @window_size
+
+      @window_size = window_size
+      reader.winsize = window_size
+      signal_process("WINCH", -pid) || signal_process("WINCH", pid)
+    rescue StandardError
+      nil
+    end
+
+    def terminal_window_size
+      rows, columns = @window_size_provider ? @window_size_provider.call : IO.console&.winsize
+      rows = DEFAULT_ROWS unless rows.to_i.positive?
+      columns = DEFAULT_COLUMNS unless columns.to_i.positive?
+      [rows, columns]
+    rescue StandardError
+      [DEFAULT_ROWS, DEFAULT_COLUMNS]
+    end
+
+    def read_chunk(reader)
+      reader.read_nonblock(READ_SIZE, exception: false).tap do |chunk|
+        return nil if chunk.nil?
+        return nil if chunk == :wait_readable
+      end
+    end
+
+    def normalize_line_endings(chunk)
+      chunk.gsub("\r\r\n", "\n").gsub("\r\n", "\n")
+    end
+
+    def capture_chunk(chunk, output, captured_bytes, truncated)
+      return [captured_bytes, truncated, ""] if truncated
+
+      remaining = @max_output_bytes - captured_bytes
+      if chunk.bytesize > remaining
+        truncated = true
+        chunk = remaining.positive? ? chunk.byteslice(0, remaining).to_s : ""
+      end
+
+      output << chunk
+      [captured_bytes + chunk.bytesize, truncated, chunk]
+    end
+
+    def wait_for_status(pid)
+      return unless pid
+
+      _, status = Process.wait2(pid)
+      status
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def exit_status(status)
+      return 1 unless status
+      return status.exitstatus if status.exited?
+      return 128 + status.termsig if status.signaled?
+
+      1
+    end
+
+    def terminate_process_group(pid)
+      signal_process("TERM", -pid) || signal_process("TERM", pid)
+      deadline = Time.now + 0.2
+      while Time.now < deadline
+        return unless process_running?(pid)
+
+        sleep 0.02
+      end
+      signal_process("KILL", -pid) || signal_process("KILL", pid)
+    end
+
+    def process_running?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def signal_process(signal, pid)
+      Process.kill(signal, pid)
+      true
+    rescue Errno::ESRCH, Errno::EINVAL, Errno::EPERM
+      false
+    end
+  end
+end

data/lib/kward/model/context_usage.rb

@@ -12,7 +12,7 @@ module Kward
     def call(provider:, model:, context_window:, context_parts:)
       return nil unless context_window
 
-      parts = redact_image_data(stringify_keys(context_parts || {}))
+      parts = redact_image_data(stringify_top_level_keys(context_parts || {}))
       return nil unless contains_session_content?(parts)
 
       payload = prompt_payload(parts)
@@ -71,7 +71,7 @@ module Kward
       ["data", "image_url"].include?(key.to_s)
     end
 
-    def stringify_keys(value)
+    def stringify_top_level_keys(value)
       return value unless value.is_a?(Hash)
 
       value.each_with_object({}) { |(key, item), result| result[key.to_s] = item }

data/lib/kward/model/payloads.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../image_attachments"
 require_relative "../message_access"
+require_relative "../tools/tool_call"
 require_relative "model_info"
 
 # Namespace for the Kward CLI agent runtime.
@@ -255,11 +256,7 @@ module Kward
     end
 
     def parse_tool_arguments(arguments)
-      return arguments if arguments.is_a?(Hash)
-
-      JSON.parse(arguments.to_s.empty? ? "{}" : arguments.to_s)
-    rescue JSON::ParserError
-      {}
+      ToolCall.parse_arguments(arguments)
     end
 
     def anthropic_tool_schema(tool)

data/lib/kward/plugin_registry.rb

@@ -23,6 +23,15 @@ module Kward
       end
     end
 
+    # Registered interactive command that takes over the composer region with a
+    # Kward-driven render and input loop. Like a slash command but with canvas
+    # rendering capabilities for games, dashboards, viewers, and similar uses.
+    InteractiveCommand = Struct.new(:name, :description, :argument_hint, :rows, :fps, :path, :handler, keyword_init: true) do
+      def entry
+        { name: name, description: description, argument_hint: argument_hint }
+      end
+    end
+
     # Read-only event passed to plugin transcript observers.
     TranscriptEvent = Struct.new(:type, :payload, keyword_init: true) do
       def to_h
@@ -167,6 +176,24 @@ module Kward
       def prompt_context(&block)
         @registry.register_prompt_context(path: @path, &block)
       end
+
+      # Registers an interactive command that takes over the composer region with
+      # a Kward-driven render and input loop. The handler receives an
+      # interactive controller object with a canvas API for drawing colored
+      # cells and reading keys. Useful for games, dashboards, and viewers.
+      #
+      # @param name [String, #to_s] command name without the leading slash
+      # @param rows [Integer] fixed canvas height in terminal rows
+      # @param fps [Numeric] frame rate for tick callbacks (1-120, default 30)
+      # @param description [String] short text shown in command listings
+      # @param argument_hint [String] optional usage hint for arguments
+      # @yieldparam ui [Object] interactive controller with canvas and key API
+      # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
+      def interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", &block)
+        @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
+      end
     end
 
     # Mutable singleton guard used while loading trusted plugin files.
@@ -207,6 +234,7 @@ module Kward
     def initialize(reserved_commands: [])
       @reserved_commands = reserved_commands.map(&:to_s)
       @commands = {}
+      @interactive_commands = {}
       @footer = nil
       @footer_path = nil
       @transcript_event_handlers = []
@@ -228,6 +256,14 @@ module Kward
       @commands[name.to_s]
     end
 
+    def interactive_commands
+      @interactive_commands.values
+    end
+
+    def interactive_command_for(name)
+      @interactive_commands[name.to_s]
+    end
+
     def footer_renderer
       @footer
     end
@@ -306,6 +342,31 @@ module Kward
       )
     end
 
+    def register_interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", path: nil, &handler)
+      name = name.to_s
+      raise "Interactive command name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
+      raise "Interactive command /#{name} requires a handler" unless handler
+
+      if @reserved_commands.include?(name) || @commands.key?(name)
+        warn "Warning: skipping Kward interactive command /#{name}: reserved command"
+        return nil
+      end
+      if @interactive_commands.key?(name)
+        warn "Warning: skipping duplicate Kward interactive command /#{name}: #{path}"
+        return nil
+      end
+
+      @interactive_commands[name] = InteractiveCommand.new(
+        name: name,
+        description: description.to_s,
+        argument_hint: argument_hint.to_s,
+        rows: [[rows.to_i, 1].max, 1].max,
+        fps: [[fps.to_f, 1].max, 120].min,
+        path: path,
+        handler: handler
+      )
+    end
+
     def register_footer(path: nil, &renderer)
       raise "Plugin footer requires a renderer" unless renderer
 

data/lib/kward/project_files.rb

@@ -0,0 +1,52 @@
+require "find"
+require "open3"
+require "pathname"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Discovers project files for prompt UI features.
+  module ProjectFiles
+    module_function
+
+    def list(root: Dir.pwd)
+      paths = git_paths(root)
+      paths = scanned_paths(root) if paths.empty?
+      paths.reject { |path| path.empty? || path.end_with?("/") }.uniq.sort
+    end
+
+    def git_paths(root)
+      output, status = Open3.capture2("git", "ls-files", "--cached", "--others", "--exclude-standard", chdir: root)
+      return [] unless status.success?
+
+      output.lines.map(&:chomp).reject(&:empty?)
+    rescue StandardError
+      []
+    end
+
+    def scanned_paths(root)
+      root_path = Pathname.new(root)
+      paths = []
+      Find.find(root_path.to_s) do |path|
+        relative = Pathname.new(path).relative_path_from(root_path).to_s
+        if File.directory?(path)
+          Find.prune if ignored_directory?(relative)
+          next
+        end
+
+        paths << relative unless ignored_file?(relative)
+      end
+      paths
+    rescue StandardError
+      []
+    end
+
+    def ignored_directory?(relative)
+      ignored_directories = %w[.git .yardoc _yardoc node_modules rdoc tmp vendor/bundle]
+      ignored_directories.include?(relative) || relative.start_with?(".git/")
+    end
+
+    def ignored_file?(relative)
+      relative.start_with?(".git/")
+    end
+  end
+end