kward 0.72.0 → 0.73.0

data/lib/kward/session_diff.rb

@@ -25,20 +25,37 @@ module Kward
       new
     end
 
+    def self.content_from_session_file(path)
+      records = File.readlines(path, chomp: true).filter_map { |line| parse_record(line) }
+      content_from_records(records)
+    rescue Errno::ENOENT, Errno::EACCES
+      ""
+    end
+
     def self.from_records(records)
       execution_records = records.select { |record| record["type"] == "tool_execution_end" }
       source_records = execution_records.empty? ? records : execution_records
       source_records.each_with_object(new) do |record, diff|
         if record["type"] == "tool_execution_end"
-          next if record["isError"] || record.dig("result", "isError")
-
-          diff.add_diff(record.dig("result", "diff"))
+          diff.add_diff(record_diff(record))
         elsif record["type"] == "message" && (record.dig("message", "role") == "tool" || record.dig("message", :role) == "tool")
           diff.add_tool_result(record.dig("message", "content") || record.dig("message", :content))
         end
       end
     end
 
+    def self.content_from_records(records)
+      records.filter_map { |record| record_diff(record) }.join("\n")
+    end
+
+    def self.record_diff(record)
+      return nil unless record["type"] == "tool_execution_end"
+      return nil if record["isError"] || record.dig("result", "isError")
+
+      diff = record.dig("result", "diff").to_s
+      diff.empty? ? nil : diff
+    end
+
     def self.count(diff)
       if (stats = truncated_diff_stats(diff))
         return stats

data/lib/kward/session_naming.rb

@@ -0,0 +1,11 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Shared session-name formatting for CLI and RPC session auto-naming.
+  module SessionNaming
+    module_function
+
+    def default_name(input)
+      input.to_s.gsub(/\s+/, " ").strip.slice(0, 120).to_s
+    end
+  end
+end

data/lib/kward/terminal_keys.rb

@@ -0,0 +1,84 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Terminal input key byte sequences grouped by semantic key.
+  module TerminalKeys
+    CTRL_SPACE = "\x00".freeze
+    CTRL_A = "\x01".freeze
+    CTRL_B = "\x02".freeze
+    CTRL_C = "\x03".freeze
+    CTRL_D = "\x04".freeze
+    CTRL_E = "\x05".freeze
+    CTRL_F = "\x06".freeze
+    CTRL_K = "\x0B".freeze
+    CTRL_L = "\x0C".freeze
+    CTRL_N = "\x0E".freeze
+    CTRL_P = "\x10".freeze
+    CTRL_Q = "\x11".freeze
+    CTRL_R = "\x12".freeze
+    CTRL_S = "\x13".freeze
+    CTRL_T = "\x14".freeze
+    CTRL_U = "\x15".freeze
+    CTRL_V = "\x16".freeze
+    CTRL_W = "\x17".freeze
+    CTRL_X = "\x18".freeze
+    CTRL_Y = "\x19".freeze
+    CTRL_Z = "\x1A".freeze
+
+    RETURN = ["\n", "\r"].freeze
+    BACKSPACE = ["\b", "\x7F"].freeze
+    TAB = ["\t", "\e[9u", "\e[9;1u", "\e[27;1;9~"].freeze
+
+    LEFT = ["\e[D", "\eOD"].freeze
+    RIGHT = ["\e[C", "\eOC"].freeze
+    UP = ["\e[A", "\eOA"].freeze
+    DOWN = ["\e[B", "\eOB"].freeze
+    HOME = ["\e[H", "\eOH", "\e[1~", "\e[7~"].freeze
+    END_KEY = ["\e[F", "\eOF", "\e[4~", "\e[8~"].freeze
+    DELETE = ["\e[3~"].freeze
+    PAGE_UP = ["\e[5~"].freeze
+    PAGE_DOWN = ["\e[6~"].freeze
+
+    SHIFT_TAB = ["\e[Z", "\e[1;2Z", "\e[9;2u", "\e[27;2;9~", "\e[1;2I"].freeze
+    CTRL_TAB = ["\e[9;5u", "\e[27;5;9~", "\e[1;5I"].freeze
+    CTRL_SHIFT_TAB = ["\e[9;6u", "\e[27;6;9~", "\e[1;6I", "\e[1;6Z"].freeze
+    SHIFT_ENTER = ["\e[13;2u", "\e[13;2~", "\e[27;2;13~", "\e\r", "\e\n"].freeze
+
+    ALT_LEFT = ["\e[1;3D", "\e[3D"].freeze
+    ALT_RIGHT = ["\e[1;3C", "\e[3C"].freeze
+    ALT_UP = ["\e[1;3A", "\e[3A"].freeze
+    ALT_DOWN = ["\e[1;3B", "\e[3B"].freeze
+
+    SHIFT_LEFT = ["\e[1;2D", "\e[2D"].freeze
+    SHIFT_RIGHT = ["\e[1;2C", "\e[2C"].freeze
+    SHIFT_UP = ["\e[1;2A", "\e[2A"].freeze
+    SHIFT_DOWN = ["\e[1;2B", "\e[2B"].freeze
+
+    CTRL_LEFT = ["\e[1;5D", "\e[5D"].freeze
+    CTRL_RIGHT = ["\e[1;5C", "\e[5C"].freeze
+    CTRL_UP = ["\e[1;5A", "\e[5A"].freeze
+    CTRL_DOWN = ["\e[1;5B", "\e[5B"].freeze
+
+    ALT_SHIFT_LEFT = ["\e[1;4D", "\e[4D"].freeze
+    ALT_SHIFT_RIGHT = ["\e[1;4C", "\e[4C"].freeze
+    ALT_SHIFT_UP = ["\e[1;4A", "\e[4A"].freeze
+    ALT_SHIFT_DOWN = ["\e[1;4B", "\e[4B"].freeze
+
+    CTRL_SHIFT_RIGHT = ["\e[1;6C", "\e[6C"].freeze
+    CTRL_SHIFT_UP = ["\e[1;6A", "\e[6A"].freeze
+    CTRL_SHIFT_DOWN = ["\e[1;6B", "\e[6B"].freeze
+
+    CTRL_T_CSI_U = "\e[116;5u".freeze
+    CTRL_W_CSI_U = "\e[119;5u".freeze
+    CTRL_NUMBER_TAB_PATTERN = /\A\e\[((?:49)|(?:5[0-7]));5u\z/.freeze
+
+    CSI_U_PATTERN = /\A\e\[(\d+)((?:;[\d:]*)*)u/.freeze
+    MODIFIED_CURSOR_PATTERN = /\A\e\[(\d+);(\d+)([CDFH])\z/.freeze
+    MODIFIED_DELETE_PATTERN = /\A\e\[3;(\d+)~\z/.freeze
+    UP_PATTERN = /\A\e\[[0-9;:]*A\z/.freeze
+    DOWN_PATTERN = /\A\e\[[0-9;:]*B\z/.freeze
+    RIGHT_PATTERN = /\A\e\[[0-9;:]*C\z/.freeze
+    LEFT_PATTERN = /\A\e\[[0-9;:]*D\z/.freeze
+    CSI_KEY_PATTERN = /\A\e\[[0-9;:]*[A-Za-z~]/.freeze
+    SS3_KEY_PATTERN = /\A\eO[A-Za-z]/.freeze
+  end
+end

data/lib/kward/terminal_sequences.rb

@@ -0,0 +1,42 @@
+require "base64"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Terminal control escape sequence builders.
+  module TerminalSequences
+    KEYBOARD_PROTOCOL_ENABLE = "\e[>25u".freeze
+    KEYBOARD_PROTOCOL_RESTORE = "\e[<u".freeze
+    BRACKETED_PASTE_ENABLE = "\e[?2004h".freeze
+    BRACKETED_PASTE_RESTORE = "\e[?2004l".freeze
+    BRACKETED_PASTE_START = "\e[200~".freeze
+    BRACKETED_PASTE_END = "\e[201~".freeze
+    SYNCHRONIZED_OUTPUT_ENABLE = "\e[?2026h".freeze
+    SYNCHRONIZED_OUTPUT_DISABLE = "\e[?2026l".freeze
+    CURSOR_SHOW = "\e[?25h".freeze
+    CURSOR_HIDE = "\e[?25l".freeze
+    CURSOR_SHAPE_DEFAULT = "\e[0 q".freeze
+    CURSOR_SHAPE_BAR = "\e[6 q".freeze
+    MOUSE_REPORTING_ENABLE = "\e[?1003h\e[?1006h".freeze
+    MOUSE_REPORTING_DISABLE = "\e[?1006l\e[?1003l".freeze
+    SGR_INVERSE = "\e[7m".freeze
+    SGR_INVERSE_OFF = "\e[27m".freeze
+
+    module_function
+
+    def scroll_region(top, bottom)
+      "\e[#{top};#{bottom}r"
+    end
+
+    def restore_scroll_region
+      "\e[r"
+    end
+
+    def move_to(row, col)
+      "\e[#{row};#{col}H"
+    end
+
+    def osc52(text)
+      "\e]52;c;#{Base64.strict_encode64(text.to_s)}\a"
+    end
+  end
+end

data/lib/kward/tools/context_for_task.rb

@@ -45,6 +45,8 @@ module Kward
 
         terms = search_terms(task)
         ranked = rank_files(files, terms)
+        return "No matching candidate files found for focused context." if ranked.empty?
+
         render_context(task: task, budget: budget, terms: terms, ranked: ranked, cancellation: cancellation)
       rescue SecurityError, Errno::ENOENT => e
         "Error: #{e.message}"

data/lib/kward/version.rb

@@ -1,5 +1,5 @@
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Current gem version.
-  VERSION = "0.72.0"
+  VERSION = "0.73.0"
 end

data/lib/kward/workers/git_guard.rb

@@ -41,6 +41,24 @@ module Kward
         Result.new(success: true, stdout: commit.stdout, stderr: commit.stderr, commit: head)
       end
 
+      def stash(message)
+        before = stash_refs
+        result = run("stash", "push", "--include-untracked", "-m", message)
+        return Result.new(success: false, stdout: result.stdout, stderr: result.stderr) unless result.success?
+        return Result.new(success: true, stdout: result.stdout, stderr: result.stderr) if result.stdout.include?("No local changes")
+
+        ref = (stash_refs - before).first || stash_refs.first
+        Result.new(success: true, stdout: result.stdout, stderr: result.stderr, commit: ref)
+      end
+
+      def apply_stash(ref)
+        run("stash", "apply", ref.to_s)
+      end
+
+      def drop_stash(ref)
+        run("stash", "drop", ref.to_s)
+      end
+
       private
 
       Result = Struct.new(:success, :stdout, :stderr, :commit, keyword_init: true) do
@@ -57,6 +75,13 @@ module Kward
         run(*args).success?
       end
 
+      def stash_refs
+        result = run("stash", "list", "--format=%gd")
+        return [] unless result.success?
+
+        result.stdout.lines.map(&:strip).reject(&:empty?)
+      end
+
       def run(*args)
         stdout, stderr, status = Open3.capture3("git", "-C", @root, *args)
         Result.new(success: status.success?, stdout: stdout.to_s, stderr: stderr.to_s)

data/lib/kward/workers/job.rb

@@ -0,0 +1,99 @@
+require "securerandom"
+require "time"
+require_relative "../config_files"
+
+module Kward
+  module Workers
+    # Persistent queue entry for a session-backed worker.
+    class Job
+      STATUSES = %w[queued running suspended ready_for_review failed blocked cancelled archived].freeze
+
+      def initialize(id: SecureRandom.hex(4), title:, session_path:, workspace_root: Dir.pwd, status: "queued", position: nil, commit_sha: nil, stash_ref: nil, error: nil, enqueued_at: Time.now.utc, started_at: nil, finished_at: nil, updated_at: nil)
+        @id = id.to_s
+        @title = title.to_s
+        @session_path = session_path.to_s
+        @workspace_root = ConfigFiles.canonical_workspace_root(workspace_root)
+        @status = status.to_s
+        @position = position
+        @commit_sha = commit_sha
+        @stash_ref = stash_ref
+        @error = error
+        @enqueued_at = enqueued_at
+        @started_at = started_at
+        @finished_at = finished_at
+        @updated_at = updated_at || enqueued_at
+      end
+
+      attr_reader :id, :title, :session_path, :workspace_root, :position, :commit_sha, :stash_ref, :error, :enqueued_at, :started_at, :finished_at, :updated_at
+
+      def status
+        @status
+      end
+
+      def update_status(status, commit_sha: nil, stash_ref: nil, error: nil, position: nil)
+        @status = status.to_s
+        @commit_sha = commit_sha unless commit_sha.nil?
+        @stash_ref = stash_ref unless stash_ref.nil?
+        @error = error unless error.nil?
+        @position = position unless position.nil?
+        now = Time.now.utc
+        @updated_at = now
+        @started_at ||= now if @status == "running"
+        @finished_at = now if %w[ready_for_review failed blocked cancelled archived].include?(@status)
+        self
+      end
+
+      def to_h
+        {
+          "id" => id,
+          "title" => title,
+          "session_path" => session_path,
+          "workspace_root" => workspace_root,
+          "status" => status,
+          "position" => position,
+          "commit_sha" => commit_sha,
+          "stash_ref" => stash_ref,
+          "error" => error,
+          "enqueued_at" => timestamp(enqueued_at),
+          "started_at" => timestamp(started_at),
+          "finished_at" => timestamp(finished_at),
+          "updated_at" => timestamp(updated_at)
+        }
+      end
+
+      def self.from_h(record)
+        new(
+          id: record.fetch("id"),
+          title: record.fetch("title"),
+          session_path: record.fetch("session_path"),
+          workspace_root: record["workspace_root"] || Dir.pwd,
+          status: record["status"] || "queued",
+          position: record["position"],
+          commit_sha: record["commit_sha"],
+          stash_ref: record["stash_ref"],
+          error: record["error"],
+          enqueued_at: parse_time(record["enqueued_at"]) || Time.now.utc,
+          started_at: parse_time(record["started_at"]),
+          finished_at: parse_time(record["finished_at"]),
+          updated_at: parse_time(record["updated_at"])
+        )
+      end
+
+      def self.parse_time(value)
+        return nil if value.to_s.empty?
+
+        Time.parse(value.to_s).utc
+      rescue ArgumentError
+        nil
+      end
+
+      private_class_method :parse_time
+
+      private
+
+      def timestamp(value)
+        value&.utc&.iso8601(3)
+      end
+    end
+  end
+end

data/lib/kward/workers/queue_runner.rb

@@ -0,0 +1,166 @@
+require_relative "../agent"
+require_relative "../config_files"
+require_relative "../model/client"
+require_relative "../tools/registry"
+require_relative "../workspace"
+require_relative "git_guard"
+require_relative "tool_policy"
+
+module Kward
+  module Workers
+    # Executes session-backed worker queue jobs one at a time.
+    class QueueRunner
+      CONTINUE_PROMPT = <<~PROMPT.freeze
+        Continue this session as an implementation worker.
+        Make the smallest correct change, preserve existing style, and run focused verification when practical.
+        Stop when the work is ready for human review.
+      PROMPT
+
+      def initialize(queue_store:, session_store:, client_factory: -> { Client.new }, prompt: nil, workspace_root: Dir.pwd, provider: nil, model: nil, reasoning_effort: nil, git_guard: nil, write_lock: nil)
+        @queue_store = queue_store
+        @session_store = session_store
+        @client_factory = client_factory
+        @prompt = prompt
+        @workspace_root = ConfigFiles.canonical_workspace_root(workspace_root)
+        @provider = provider
+        @model = model
+        @reasoning_effort = reasoning_effort
+        @git_guard = git_guard || GitGuard.new(root: @workspace_root)
+        @write_lock = write_lock
+      end
+
+      def run_next
+        record = @queue_store.next_queued
+        return nil unless record
+
+        run_job(record)
+      end
+
+      def run_all
+        results = []
+        loop do
+          record = run_next
+          break unless record
+
+          results << record
+          break unless record["status"] == "ready_for_review"
+        end
+        results
+      end
+
+      def suspend(id)
+        record = find_job(id)
+        raise ArgumentError, "Worker job #{id} is not running" unless record["status"] == "running"
+
+        stash_ref = stash_worker_changes(record)
+        @queue_store.update_status(record.fetch("id"), "suspended", stash_ref: stash_ref, error: "")
+      rescue StandardError => e
+        @queue_store.update_status(id, "blocked", error: e.message)
+      end
+
+      def resume(id)
+        record = find_job(id)
+        raise ArgumentError, "Worker job #{id} is not suspended" unless record["status"] == "suspended"
+
+        restore_worker_changes(record)
+        queued = @queue_store.update_status(record.fetch("id"), "queued", stash_ref: "", error: "")
+        run_job(queued, require_clean: false)
+      rescue DirtyWorkspaceError => e
+        @queue_store.update_status(id, "blocked", error: e.message)
+      rescue StandardError => e
+        @queue_store.update_status(id, "blocked", error: e.message)
+      end
+
+      private
+
+      def run_job(record, require_clean: true)
+        id = record.fetch("id")
+        ensure_clean_workspace!(record) if require_clean
+        @queue_store.update_status(id, "running", error: "")
+        session, conversation = load_job_session(record)
+        agent = Agent.new(client: @client_factory.call, tool_registry: tool_registry(record, id), conversation: conversation)
+        report = agent.ask(CONTINUE_PROMPT)
+        commit = commit_if_needed(record)
+        session.append_message({ role: "assistant", content: completion_report(report, commit) }) if commit
+        @queue_store.update_status(id, "ready_for_review", commit_sha: commit, error: "")
+      rescue DirtyWorkspaceError => e
+        @queue_store.update_status(id, "blocked", error: e.message)
+      rescue StandardError => e
+        @queue_store.update_status(id, "failed", error: e.message)
+      end
+
+      def ensure_clean_workspace!(record)
+        return unless @git_guard.repository?
+        return if @git_guard.clean?
+
+        raise DirtyWorkspaceError, "Workspace is dirty; clean or stash changes before running worker #{record.fetch('id')}"
+      end
+
+      def find_job(id)
+        @queue_store.find(id) || raise(ArgumentError, "Unknown worker job: #{id}")
+      end
+
+      def stash_worker_changes(record)
+        return "" unless @git_guard.repository?
+        return "" if @git_guard.clean?
+
+        result = @git_guard.stash("Kward worker #{record.fetch('id')}: #{record.fetch('title')}")
+        raise "Worker changes could not be stashed: #{result.output}" unless result.success?
+
+        result.commit.to_s
+      end
+
+      def restore_worker_changes(record)
+        ensure_clean_workspace!(record)
+        ref = record["stash_ref"].to_s
+        return if ref.empty?
+
+        apply = @git_guard.apply_stash(ref)
+        raise "Worker stash could not be restored: #{apply.output}" unless apply.success?
+
+        drop = @git_guard.drop_stash(ref)
+        raise "Worker stash could not be dropped: #{drop.output}" unless drop.success?
+      end
+
+      def load_job_session(record)
+        @session_store.load(
+          record.fetch("session_path"),
+          workspace: Workspace.new(root: record["workspace_root"] || @workspace_root),
+          provider: @provider,
+          model: @model,
+          reasoning_effort: @reasoning_effort
+        )
+      end
+
+      def tool_registry(record, writer_id)
+        ToolRegistry.new(
+          workspace: Workspace.new(root: record["workspace_root"] || @workspace_root),
+          prompt: @prompt,
+          allowed_tool_names: ToolPolicy.allowed_tool_names("implementation"),
+          write_lock: @write_lock,
+          writer_id: writer_id
+        )
+      end
+
+      def commit_if_needed(record)
+        return nil unless @git_guard.repository?
+        return nil if @git_guard.clean?
+
+        result = @git_guard.commit_all(commit_message(record))
+        raise "Worker changed files but commit failed: #{result.output}" unless result.success?
+
+        result.commit
+      end
+
+      def commit_message(record)
+        "Kward worker #{record.fetch('id')}: #{record.fetch('title')}"
+      end
+
+      def completion_report(report, commit)
+        [report, "", "Committed workspace changes: #{commit}"].join("\n")
+      end
+
+      class DirtyWorkspaceError < StandardError; end
+    end
+  end
+end

data/lib/kward/workers/queue_store.rb

@@ -0,0 +1,112 @@
+require "fileutils"
+require "json"
+require_relative "../config_files"
+require_relative "job"
+
+module Kward
+  module Workers
+    # JSON-backed queue store for session-backed worker jobs.
+    class QueueStore
+      def initialize(path: File.join(ConfigFiles.config_dir, "worker_queue.json"))
+        @path = path
+        @mutex = Mutex.new
+      end
+
+      attr_reader :path
+
+      def enqueue(title:, session_path:, workspace_root:, id: nil)
+        job = Job.new(
+          id: id || SecureRandom.hex(4),
+          title: title,
+          session_path: session_path,
+          workspace_root: workspace_root,
+          position: next_position
+        )
+        upsert(job)
+        job
+      end
+
+      def upsert(job)
+        record = job.respond_to?(:to_h) ? job.to_h : job.to_h
+        update_records do |records|
+          index = records.index { |item| item["id"] == record["id"] }
+          index ? records[index] = record : records << record
+          normalize_positions(records)
+        end
+        record
+      end
+
+      def list(include_archived: false)
+        records = read_records
+        records = records.reject { |record| record["status"] == "archived" } unless include_archived
+        sorted(records)
+      end
+
+      def find(id)
+        read_records.find { |record| record["id"] == id.to_s }
+      end
+
+      def update_status(id, status, **values)
+        record = nil
+        update_records do |records|
+          index = records.index { |item| item["id"] == id.to_s }
+          raise ArgumentError, "Unknown worker job: #{id}" unless index
+
+          job = Job.from_h(records[index])
+          job.update_status(status, **values)
+          record = job.to_h
+          records[index] = record
+          normalize_positions(records)
+        end
+        record
+      end
+
+      def archive(id)
+        update_status(id, "archived")
+      end
+
+      def next_queued
+        list.find { |record| record["status"] == "queued" }
+      end
+
+      private
+
+      def next_position
+        last = list(include_archived: true).map { |record| record["position"].to_i }.max
+        last ? last + 1 : 1
+      end
+
+      def read_records
+        @mutex.synchronize { read_records_unlocked }
+      end
+
+      def read_records_unlocked
+        return [] unless File.exist?(@path)
+
+        data = JSON.parse(File.read(@path))
+        data.is_a?(Array) ? data : []
+      rescue JSON::ParserError
+        raise "Invalid worker queue JSON: #{@path}"
+      end
+
+      def update_records
+        @mutex.synchronize do
+          records = read_records_unlocked
+          yield records
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.write(@path, JSON.pretty_generate(sorted(records)) + "\n")
+        end
+      end
+
+      def sorted(records)
+        records.sort_by { |record| [record["position"].to_i, record["enqueued_at"].to_s, record["id"].to_s] }
+      end
+
+      def normalize_positions(records)
+        sorted(records).each_with_index do |record, index|
+          record["position"] = index + 1
+        end
+      end
+    end
+  end
+end

data/lib/kward/workers.rb

@@ -1,6 +1,9 @@
 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"