kward 0.71.0 → 0.73.0

data/lib/kward/workers/worker.rb

@@ -0,0 +1,82 @@
+require "securerandom"
+require "time"
+require_relative "../config_files"
+require_relative "../cancellation"
+
+module Kward
+  module Workers
+    # Runtime record for one independent unit of agent work.
+    class Worker
+      STATUSES = %w[idle queued running ready failed cancelled archived].freeze
+
+      def initialize(id: SecureRandom.hex(4), title:, role:, workspace_root: Dir.pwd, status: "idle", prompt: nil, conversation: nil, session: nil, cancellation: Cancellation.new, created_at: Time.now.utc)
+        @id = id
+        @title = title.to_s
+        @role = role.to_s
+        @workspace_root = ConfigFiles.canonical_workspace_root(workspace_root)
+        @status = status.to_s
+        @prompt = prompt.to_s
+        @conversation = conversation
+        @session = session
+        @cancellation = cancellation
+        @created_at = created_at
+        @updated_at = created_at
+        @started_at = nil
+        @finished_at = nil
+        @report = nil
+        @error = nil
+        @thread = nil
+        @event_history = []
+        @event_queue = Queue.new
+      end
+
+      attr_reader :id, :title, :role, :workspace_root, :prompt, :conversation, :session, :cancellation, :created_at, :updated_at, :started_at, :finished_at, :report, :error, :thread, :event_history, :event_queue
+      attr_writer :conversation, :session, :thread
+
+      def status
+        @status
+      end
+
+      def update_status(status, error: nil, report: nil)
+        @status = status.to_s
+        @error = error unless error.nil?
+        @report = report unless report.nil?
+        now = Time.now.utc
+        @updated_at = now
+        @started_at ||= now if @status == "running"
+        @finished_at = now if %w[ready failed cancelled archived].include?(@status)
+        self
+      end
+
+      def record_event(event)
+        @event_history << event
+        @event_queue << event
+      end
+
+      def to_h
+        {
+          "id" => id,
+          "title" => title,
+          "role" => role,
+          "status" => status,
+          "prompt" => prompt,
+          "workspace_root" => workspace_root,
+          "session_id" => session&.id,
+          "session_path" => session&.path,
+          "created_at" => timestamp(created_at),
+          "updated_at" => timestamp(updated_at),
+          "started_at" => timestamp(started_at),
+          "finished_at" => timestamp(finished_at),
+          "report" => report,
+          "error" => error
+        }
+      end
+
+      private
+
+      def timestamp(value)
+        value&.utc&.iso8601(3)
+      end
+    end
+  end
+end

data/lib/kward/workers/write_lock.rb

@@ -0,0 +1,38 @@
+require "thread"
+
+module Kward
+  module Workers
+    # Cooperative ownership guard for workspace-mutating worker tools.
+    class WriteLock
+      def initialize
+        @owner_id = nil
+        @mutex = Mutex.new
+      end
+
+      attr_reader :owner_id
+
+      def acquire(owner_id)
+        owner = owner_id.to_s
+        return false if owner.empty?
+
+        @mutex.synchronize do
+          return true if @owner_id == owner
+          return false if @owner_id
+
+          @owner_id = owner
+          true
+        end
+      end
+
+      def owned_by?(owner_id)
+        @mutex.synchronize { @owner_id == owner_id.to_s }
+      end
+
+      def release(owner_id)
+        @mutex.synchronize do
+          @owner_id = nil if @owner_id == owner_id.to_s
+        end
+      end
+    end
+  end
+end

data/lib/kward/workers.rb

@@ -0,0 +1,10 @@
+require_relative "workers/git_guard"
+require_relative "workers/job"
+require_relative "workers/live_view"
+require_relative "workers/manager"
+require_relative "workers/queue_runner"
+require_relative "workers/queue_store"
+require_relative "workers/store"
+require_relative "workers/tool_policy"
+require_relative "workers/write_lock"
+require_relative "workers/worker"

data/lib/kward/workspace.rb

@@ -1,6 +1,5 @@
-require "open3"
 require "pathname"
-require "timeout"
+require_relative "local_command_runner"
 require_relative "session_diff"
 
 # Namespace for the Kward CLI agent runtime.
@@ -23,6 +22,7 @@ module Kward
     MAX_COMMAND_OUTPUT_BYTES = 128 * 1024
     MAX_EDIT_DIFF_BYTES = 8 * 1024
     DEFAULT_COMMAND_TIMEOUT_SECONDS = 30
+    EXPECTED_FILE_ERRORS = [SecurityError, Errno::ENOENT, Errno::EACCES, Errno::EPERM, Errno::EISDIR, Errno::ENOTDIR].freeze
 
     # Creates an object for workspace filesystem and shell operations.
     def initialize(root: Dir.pwd, max_file_bytes: MAX_FILE_BYTES, max_read_output_bytes: MAX_READ_OUTPUT_BYTES, max_read_output_lines: MAX_READ_OUTPUT_LINES, max_command_output_bytes: MAX_COMMAND_OUTPUT_BYTES, guardrails: true)
@@ -45,7 +45,7 @@ module Kward
       Dir.children(resolved).sort.map do |entry|
         File.directory?(File.join(resolved, entry)) ? "#{entry}/" : entry
       end.join("\n")
-    rescue SecurityError, Errno::ENOENT => e
+    rescue *EXPECTED_FILE_ERRORS => e
       "Error: #{e.message}"
     end
 
@@ -54,7 +54,7 @@ module Kward
     # The returned string is user/model-facing and includes continuation notices
     # when output is truncated. Errors are returned as `"Error: ..."` strings so
     # tool calls can be persisted in the conversation without raising.
-    def read_file(path, offset: nil, limit: nil)
+    def read_file(path, offset: nil, limit: nil, mode: nil, max_bytes: nil)
       resolved = workspace_path(path)
       return "Error: not a file: #{path}" unless File.file?(resolved)
 
@@ -64,8 +64,25 @@ module Kward
       content = File.read(resolved)
       return "Error: not a text file: #{path}" if binary_content?(content)
 
-      large_file_outline_response(path, content, offset: offset, limit: limit) || read_file_slice(content, offset: offset, limit: limit)
-    rescue SecurityError, Errno::ENOENT => e
+      read_mode = normalize_read_mode(mode)
+      return read_mode if read_mode.is_a?(String)
+
+      output_budget = read_output_budget(max_bytes)
+      return output_budget if output_budget.is_a?(String)
+
+      case read_mode
+      when :outline
+        file_structure_summary(path, content)
+      when :preview
+        read_file_slice(content, offset: offset, limit: limit || 120, max_bytes: output_budget)
+      when :range
+        read_file_slice(content, offset: offset, limit: limit, max_bytes: output_budget)
+      when :full
+        read_file_slice(content, offset: offset, limit: limit, max_bytes: output_budget)
+      else
+        large_file_outline_response(path, content, offset: offset, limit: limit) || read_file_slice(content, offset: offset, limit: limit, max_bytes: output_budget)
+      end
+    rescue *EXPECTED_FILE_ERRORS => e
       "Error: #{e.message}"
     end
 
@@ -80,12 +97,8 @@ module Kward
       content = File.read(resolved)
       return "Error: not a text file: #{path}" if binary_content?(content)
 
-      lines = content.split("\n", -1)
-      outline = source_outline(lines)
-      return "No recognizable source structure found in #{path}." if outline.empty?
-
-      (["# File structure: #{path}", "- Lines: #{lines.length}", "- Bytes: #{content.bytesize}", "", "## Outline"] + outline).join("\n")
-    rescue SecurityError, Errno::ENOENT => e
+      file_structure_summary(path, content)
+    rescue *EXPECTED_FILE_ERRORS => e
       "Error: #{e.message}"
     end
 
@@ -107,7 +120,7 @@ module Kward
       output = "Wrote #{content.bytesize} bytes to #{path}"
       output << "\n#{truncated_diff(path, old_content, content)}" if old_content && old_content != content
       output
-    rescue SecurityError, Errno::ENOENT => e
+    rescue *EXPECTED_FILE_ERRORS => e
       "Error: #{e.message}"
     end
 
@@ -130,7 +143,7 @@ module Kward
 
       File.write(resolved, result[:content])
       "Edited #{path}: replaced #{result[:count]} block(s)\n#{truncated_diff(path, content, result[:content])}"
-    rescue SecurityError, Errno::ENOENT => e
+    rescue *EXPECTED_FILE_ERRORS => e
       "Error: #{e.message}"
     end
 
@@ -147,24 +160,14 @@ module Kward
       timeout_seconds = DEFAULT_COMMAND_TIMEOUT_SECONDS if timeout_seconds <= 0
       cancellation&.raise_if_cancelled!
 
-      Open3.popen3(command, chdir: @root.to_s) do |stdin, stdout, stderr, wait_thread|
-        stdin.close
-        stdout_reader = Thread.new { stdout.read }
-        stderr_reader = Thread.new { stderr.read }
-        cancellation&.on_cancel { terminate_process(wait_thread.pid) }
-        status = wait_for_process(wait_thread, timeout_seconds, cancellation)
-
-        output = +"Exit status: #{status.exitstatus}\n"
-        output << "\nSTDOUT:\n#{stdout_reader.value}" unless stdout_reader.value.empty?
-        output << "\nSTDERR:\n#{stderr_reader.value}" unless stderr_reader.value.empty?
-        truncate_output(output)
-      rescue Timeout::Error
-        terminate_process(wait_thread.pid)
-        "Error: command timed out after #{timeout_seconds} seconds"
-      ensure
-        stdout_reader&.kill if stdout_reader&.alive?
-        stderr_reader&.kill if stderr_reader&.alive?
-      end
+      result = LocalCommandRunner.new(timeout_seconds: timeout_seconds, max_output_bytes: @max_command_output_bytes).run(command, cwd: @root.to_s, cancellation: cancellation)
+      return "Error: command timed out after #{timeout_seconds} seconds" if result.timed_out
+
+      output = +"Exit status: #{result.exit_status}\n"
+      output << "\nSTDOUT:\n#{result.stdout}" unless result.stdout.empty?
+      output << "\nSTDERR:\n#{result.stderr}" unless result.stderr.empty?
+      output << "\n... truncated to #{@max_command_output_bytes} bytes" if result.truncated
+      truncate_output(output)
     rescue Errno::ENOENT, ArgumentError => e
       "Error: #{e.message}"
     end
@@ -235,24 +238,96 @@ module Kward
         "First #{preview_limit} lines:",
         preview,
         "",
-        "[Use read_file with offset=#{preview_limit + 1} and limit to continue, or request a specific section from the outline.]"
+        "[Use read_file with mode=\"range\", offset=#{preview_limit + 1}, and limit to continue; mode=\"outline\" for only the outline; or request a specific section from the outline.]"
       ].join("\n")
     end
 
+    def file_structure_summary(path, content)
+      lines = content.split("\n", -1)
+      outline = source_outline(lines)
+      return "No recognizable source structure found in #{path}." if outline.empty?
+
+      (["# File structure: #{path}", "- Lines: #{lines.length}", "- Bytes: #{content.bytesize}", "", "## Outline"] + outline).join("\n")
+    end
+
     def source_outline(lines)
-      outline = []
+      entries = source_outline_entries(lines)
+      entries.first(80).map do |entry|
+        range = entry[:end_line] && entry[:end_line] != entry[:line] ? " (range #{entry[:line]}-#{entry[:end_line]}, #{entry[:kind]})" : " (#{entry[:kind]})"
+        "line #{entry[:line]}: #{'  ' * [entry[:indent] / 2, 6].min}#{entry[:signature]}#{range}"
+      end
+    end
+
+    def source_outline_entries(lines)
+      candidates = []
       lines.each_with_index do |line, index|
-        stripped = line.strip
-        next unless stripped.match?(/\A(class|module|def)\s+/) || stripped.match?(/\A(function|async function)\s+/) || stripped.match?(/\A(export\s+)?(class|interface|type)\s+/)
+        declaration = source_declaration(line.strip)
+        next unless declaration
 
-        indent = line[/\A\s*/].to_s.length
-        outline << "line #{index + 1}: #{'  ' * [indent / 2, 6].min}#{stripped}"
-        break if outline.length >= 80
+        candidates << declaration.merge(line: index + 1, indent: line[/\A\s*/].to_s.length)
       end
-      outline
+      candidates.each_with_index do |entry, index|
+        following = candidates[(index + 1)..]&.find { |candidate| candidate[:indent] <= entry[:indent] }
+        entry[:end_line] = following ? following[:line] - 1 : last_content_line(lines)
+      end
+      candidates
     end
 
-    def read_file_slice(content, offset:, limit:)
+    def source_declaration(stripped)
+      case stripped
+      when /\A(module)\s+(.+)/
+        { kind: "module", signature: stripped }
+      when /\A(class)\s+(.+)/
+        { kind: "class", signature: stripped }
+      when /\A(async\s+def|def)\s+(.+)/
+        { kind: "function", signature: stripped }
+      when /\A(export\s+)?(async\s+)?function\s+(.+)/
+        { kind: "function", signature: stripped }
+      when /\A(async\s+)?(?:get\s+|set\s+)?(?:constructor|[A-Za-z_$][\w$]*)\s*\([^;]*\)\s*(?::\s*[^{}]+)?\s*(?:\{\}|\{|=>)?\z/
+        { kind: "method", signature: stripped } unless stripped.match?(/\A(if|for|while|switch|catch)\b/)
+      when /\A(export\s+)?(class|interface|type|enum)\s+(.+)/
+        { kind: Regexp.last_match(2), signature: stripped }
+      when /\A(?:export\s+)?(?:const|let|var)\s+\w+\s*=.*=>/
+        { kind: "function", signature: stripped }
+      when /\Afunc\s+(.+)/
+        { kind: "function", signature: stripped }
+      when /\Atype\s+\w+\s+(struct|interface)\b/
+        { kind: Regexp.last_match(1), signature: stripped }
+      when /\A(pub\s+)?(async\s+)?fn\s+(.+)/
+        { kind: "function", signature: stripped }
+      when /\A(pub\s+)?(struct|enum|trait|impl)\b(.+)?/
+        { kind: Regexp.last_match(2), signature: stripped }
+      when /\A(?:public|private|protected|internal|static|final|abstract|async|override|virtual|sealed|readonly|partial|\s)+\s*(class|interface|enum|record)\s+(.+)/
+        { kind: Regexp.last_match(1), signature: stripped }
+      when /\A(?:public|private|protected|internal|static|final|abstract|async|override|virtual|sealed|readonly|partial|\s)+\s*\S[^{;=]*\w+\s*\([^;]*\)\s*(?:\{|=>)?\z/
+        { kind: "method", signature: stripped }
+      end
+    end
+
+    def last_content_line(lines)
+      index = lines.rindex { |line| !line.strip.empty? }
+      index ? index + 1 : lines.length
+    end
+
+    def normalize_read_mode(mode)
+      return nil if mode.nil? || mode.to_s.empty?
+
+      value = mode.to_s.downcase
+      return value.to_sym if %w[preview outline range full].include?(value)
+
+      "Error: mode must be one of preview, outline, range, full"
+    end
+
+    def read_output_budget(max_bytes)
+      return @max_read_output_bytes if max_bytes.nil?
+
+      value = max_bytes.to_i
+      return "Error: max_bytes must be positive" unless value.positive?
+
+      [value, @max_read_output_bytes].min
+    end
+
+    def read_file_slice(content, offset:, limit:, max_bytes: @max_read_output_bytes)
       lines = content.split("\n", -1)
       lines = [""] if lines.empty?
       start_index = read_start_index(offset)
@@ -263,7 +338,7 @@ module Kward
 
       selected_end = user_limit ? [start_index + user_limit, lines.length].min : lines.length
       selected_lines = lines[start_index...selected_end]
-      truncated = truncate_read_lines(selected_lines)
+      truncated = truncate_read_lines(selected_lines, max_bytes: max_bytes)
       return truncated[:error] if truncated[:error]
 
       output = truncated[:content]
@@ -272,7 +347,8 @@ module Kward
           start_index: start_index,
           output_lines: truncated[:line_count],
           total_lines: lines.length,
-          truncated_by: truncated[:truncated_by]
+          truncated_by: truncated[:truncated_by],
+          max_bytes: max_bytes
         )
       elsif user_limit && selected_end < lines.length
         output << "\n\n[#{lines.length - selected_end} more lines in file. Use offset=#{selected_end + 1} to continue.]"
@@ -300,11 +376,11 @@ module Kward
       value
     end
 
-    def truncate_read_lines(lines)
+    def truncate_read_lines(lines, max_bytes: @max_read_output_bytes)
       first_line = lines.first.to_s
-      if first_line.bytesize > @max_read_output_bytes
+      if first_line.bytesize > max_bytes
         return {
-          error: "Error: first line is #{first_line.bytesize} bytes, exceeds #{@max_read_output_bytes} byte read limit. Use run_shell_command with sed/head to inspect smaller chunks."
+          error: "Error: first line is #{first_line.bytesize} bytes, exceeds #{max_bytes} byte read limit. Use run_shell_command with sed/head to inspect smaller chunks."
         }
       end
 
@@ -319,7 +395,7 @@ module Kward
 
         separator_bytes = output_lines.empty? ? 0 : 1
         next_bytes = line.bytesize + separator_bytes
-        if bytes + next_bytes > @max_read_output_bytes
+        if bytes + next_bytes > max_bytes
           truncated_by = "bytes"
           break
         end
@@ -336,10 +412,10 @@ module Kward
       }
     end
 
-    def read_truncation_notice(start_index:, output_lines:, total_lines:, truncated_by:)
+    def read_truncation_notice(start_index:, output_lines:, total_lines:, truncated_by:, max_bytes: @max_read_output_bytes)
       end_line = start_index + output_lines
       next_offset = end_line + 1
-      detail = truncated_by == "lines" ? "#{@max_read_output_lines} line limit" : "#{@max_read_output_bytes} byte limit"
+      detail = truncated_by == "lines" ? "#{@max_read_output_lines} line limit" : "#{max_bytes} byte limit"
       "\n\n[Showing lines #{start_index + 1}-#{end_line} of #{total_lines} (#{detail}). Use offset=#{next_offset} to continue.]"
     end
 
@@ -436,43 +512,5 @@ module Kward
       output.byteslice(0, @max_command_output_bytes) << "\n... truncated to #{@max_command_output_bytes} bytes"
     end
 
-    def wait_for_process(wait_thread, timeout_seconds, cancellation)
-      deadline = Time.now + timeout_seconds
-      loop do
-        cancellation&.raise_if_cancelled!
-        if wait_thread.join(0.05)
-          cancellation&.raise_if_cancelled!
-          return wait_thread.value
-        end
-        raise Timeout::Error if Time.now >= deadline
-      end
-    end
-
-    def terminate_process(pid)
-      return unless 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)
-    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
-      false
-    end
   end
 end