kward 0.71.0 → 0.73.0

data/lib/kward/workers/manager.rb

@@ -0,0 +1,288 @@
+require "timeout"
+require_relative "../agent"
+require_relative "../cancellation"
+require_relative "../conversation"
+require_relative "../model/client"
+require_relative "../session_store"
+require_relative "../tools/registry"
+require_relative "../workspace"
+require_relative "git_guard"
+require_relative "tool_policy"
+require_relative "worker"
+
+module Kward
+  module Workers
+    # Coordinates background worker execution and role-specific tool policy.
+    class Manager
+      DEFAULT_TIMEOUT_SECONDS = 180
+
+      def initialize(client_factory: -> { Client.new }, prompt: nil, workspace_root: Dir.pwd, timeout_seconds: DEFAULT_TIMEOUT_SECONDS, on_status_change: nil, session_store: nil, provider: nil, model: nil, reasoning_effort: nil, write_lock: nil, worker_store: nil, git_guard: nil, write_lane_available: -> { true })
+        @client_factory = client_factory
+        @prompt = prompt
+        @workspace_root = ConfigFiles.canonical_workspace_root(workspace_root)
+        @timeout_seconds = timeout_seconds
+        @on_status_change = on_status_change
+        @session_store = session_store
+        @provider = provider
+        @model = model
+        @reasoning_effort = reasoning_effort
+        @write_lock = write_lock
+        @worker_store = worker_store
+        @git_guard = git_guard || GitGuard.new(root: @workspace_root)
+        @write_lane_available = write_lane_available
+        @workers = {}
+        @mutex = Mutex.new
+      end
+
+      def start(role:, prompt:, title: nil, id: nil)
+        worker = build_worker(role: role, prompt: prompt, title: title, id: id)
+        enqueue(worker)
+      end
+
+      def continue(id, role:, prompt:, title: nil)
+        archived = nil
+        worker = build_worker(role: role, prompt: prompt, title: title, id: id)
+        @mutex.synchronize do
+          archived = @workers.delete(id.to_s)
+          @workers[worker.id] = worker
+        end
+        archived&.update_status("archived")
+        @worker_store&.archive(id) if archived || @worker_store&.find(id)
+        enqueue(worker, store: false)
+      end
+
+      def list
+        @mutex.synchronize { @workers.values.reject { |worker| worker.status == "archived" }.sort_by(&:created_at) }
+      end
+
+      def find(id)
+        @mutex.synchronize { @workers[id.to_s] }
+      end
+
+      def cancel(id)
+        worker = find(id) || raise(ArgumentError, "Unknown worker: #{id}")
+        worker.cancellation.cancel!
+        worker.thread.raise(Cancellation::CancelledError, "cancelled") if worker.thread&.alive?
+        update_status(worker, "cancelled")
+      end
+
+      def archive(id)
+        worker = find(id) || raise(ArgumentError, "Unknown worker: #{id}")
+        worker.cancellation.cancel! if %w[queued running].include?(worker.status)
+        worker.thread.raise(Cancellation::CancelledError, "cancelled") if worker.thread&.alive?
+        update_status(worker, "archived")
+      end
+
+      private
+
+      def build_worker(role:, prompt:, title: nil, id: nil)
+        Worker.new(
+          id: id || SecureRandom.hex(4),
+          title: title || title_for(prompt),
+          role: role,
+          prompt: prompt,
+          workspace_root: @workspace_root,
+          status: "queued"
+        )
+      end
+
+      def enqueue(worker, store: true)
+        @mutex.synchronize { @workers[worker.id] = worker }
+        @worker_store&.upsert(worker) if store
+        worker.thread = Thread.new { run_worker(worker) }
+        worker.thread.report_on_exception = false
+        worker
+      end
+
+      def run_worker(worker)
+        conversation = Conversation.new(
+          system_message: { role: "system", content: system_message(worker) },
+          workspace_root: worker.workspace_root,
+          provider: @provider,
+          model: @model,
+          reasoning_effort: @reasoning_effort
+        )
+        worker.conversation = conversation
+        attach_session(worker, conversation)
+        writer_id = wait_for_worker_writer(worker)
+        update_status(worker, "running")
+        registry = ToolRegistry.new(
+          workspace: Workspace.new(root: worker.workspace_root),
+          prompt: @prompt,
+          allowed_tool_names: ToolPolicy.allowed_tool_names(worker.role),
+          write_lock: @write_lock,
+          writer_id: writer_id
+        )
+        agent = Agent.new(client: @client_factory.call, tool_registry: registry, conversation: conversation)
+        report = Timeout.timeout(@timeout_seconds, WorkerTimeoutError) do
+          agent.ask(worker_prompt(worker), cancellation: worker.cancellation) do |event|
+            worker.record_event(event)
+          end
+        end
+        report = finalize_write_worker(worker, report)
+        update_status(worker, "ready", report: report, error: "")
+      rescue WorkerTimeoutError
+        update_status(worker, "failed", error: "Worker timed out after #{@timeout_seconds} seconds")
+      rescue Cancellation::CancelledError
+        update_status(worker, "cancelled")
+      rescue StandardError => e
+        update_status(worker, "failed", error: e.message)
+      ensure
+        release_worker_writer(worker)
+      end
+
+      def update_status(worker, status, **values)
+        return worker if worker.status == "archived" && status.to_s != "archived"
+
+        worker.update_status(status, **values)
+        @worker_store&.upsert(worker)
+        @on_status_change&.call(worker)
+        worker
+      end
+
+      def wait_for_worker_writer(worker)
+        return nil unless ToolPolicy.write_capable?(worker.role)
+
+        loop do
+          worker.cancellation.raise_if_cancelled!
+          wait_for_write_lane_available(worker)
+          wait_for_clean_workspace(worker)
+          return worker.id unless @write_lock
+
+          release_foreground_writer_if_clean
+          return worker.id if @write_lock.acquire(worker.id)
+
+          sleep 0.1
+        end
+      end
+
+      def wait_for_write_lane_available(worker)
+        until @write_lane_available.call
+          worker.cancellation.raise_if_cancelled!
+          sleep 0.1
+        end
+      end
+
+      def wait_for_clean_workspace(worker)
+        return unless @git_guard.repository?
+
+        until @git_guard.clean?
+          worker.cancellation.raise_if_cancelled!
+          sleep 0.5
+        end
+      end
+
+      def release_foreground_writer_if_clean
+        return unless @write_lock&.owned_by?("implementation")
+        return unless @git_guard.repository?
+        return unless @git_guard.clean?
+
+        @write_lock.release("implementation")
+      end
+
+      def finalize_write_worker(worker, report)
+        return report unless ToolPolicy.write_capable?(worker.role)
+        return report unless @git_guard.repository?
+        return report if @git_guard.clean?
+
+        commit = @git_guard.commit_all(commit_message(worker))
+        unless commit.success?
+          raise "Worker changed files but commit failed: #{commit.output}"
+        end
+
+        [report, "", "Committed workspace changes: #{commit.commit}"].join("\n")
+      end
+
+      def commit_message(worker)
+        "Kward worker #{worker.id}: #{worker.title}"
+      end
+
+      def release_worker_writer(worker)
+        return unless ToolPolicy.write_capable?(worker.role)
+
+        @write_lock&.release(worker.id)
+      end
+
+      def attach_session(worker, conversation)
+        return unless @session_store
+
+        session = @session_store.create(provider: @provider, model: @model, reasoning_effort: @reasoning_effort)
+        session.rename("#{worker.role}: #{worker.title}")
+        session.attach(conversation)
+        worker.session = session
+        @worker_store&.upsert(worker)
+        @on_status_change&.call(worker)
+      rescue StandardError
+        nil
+      end
+
+      def worker_prompt(worker)
+        return request_prompt(worker.prompt) if worker.role == "request"
+
+        worker.prompt
+      end
+
+      def system_message(worker)
+        return request_system_message if worker.role == "request"
+
+        "You are a Kward worker. Complete the user's task carefully."
+      end
+
+      def request_system_message
+        <<~SYSTEM
+          You are a Kward request worker running the read-only exploration phase.
+          Inspect the workspace, map relevant terrain, and produce a practical review for the user.
+          Do not edit files, write files, delete files, alter configuration, or claim implementation work was done.
+        SYSTEM
+      end
+
+      def request_prompt(prompt)
+        <<~PROMPT
+          #{prompt}
+
+          ---
+
+          You are handling this as a structured Kward background request.
+          First perform a read-only exploration phase. Inspect relevant files and documentation, reason about the request, and prepare a reviewable result for the user.
+          Do not modify files, write files, delete files, alter configuration, run destructive commands, or claim implementation work was done.
+
+          Return a concise request review with these sections:
+          # Request Review: <title>
+
+          ## Request
+          Restate the user's request.
+
+          ## Summary
+          The short answer.
+
+          ## Relevant files
+          Bullet list of likely files and why they matter.
+
+          ## Findings
+          What you discovered.
+
+          ## Recommended next step
+          A practical next step. If implementation appears useful, say so clearly, but do not implement it.
+
+          ## Risks
+          Important risks or unknowns.
+
+          ## Verification
+          Focused verification commands or checks.
+
+          ## Open questions
+          Decisions the user should make before proceeding.
+
+          End by asking: Should we proceed?
+        PROMPT
+      end
+
+      def title_for(prompt)
+        text = prompt.to_s.strip.gsub(/\s+/, " ")
+        text.empty? ? "Untitled worker" : text[0, 80]
+      end
+
+      class WorkerTimeoutError < StandardError; 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/store.rb

@@ -0,0 +1,72 @@
+require "fileutils"
+require "json"
+require_relative "../config_files"
+
+module Kward
+  module Workers
+    # JSON-backed metadata store for worker records.
+    class Store
+      def initialize(path: File.join(ConfigFiles.config_dir, "workers.json"))
+        @path = path
+        @mutex = Mutex.new
+      end
+
+      attr_reader :path
+
+      def upsert(worker)
+        record = worker.respond_to?(:to_h) ? worker.to_h : worker.to_h
+        update_records do |records|
+          index = records.index { |item| item["id"] == record["id"] }
+          index ? records[index] = record : records << record
+        end
+        record
+      end
+
+      def list(include_archived: false)
+        records = read_records
+        records = records.reject { |record| record["status"] == "archived" } unless include_archived
+        records.sort_by { |record| record["created_at"].to_s }
+      end
+
+      def find(id)
+        read_records.find { |record| record["id"] == id.to_s }
+      end
+
+      def archive(id)
+        record = nil
+        update_records do |records|
+          index = records.index { |item| item["id"] == id.to_s }
+          raise ArgumentError, "Unknown worker: #{id}" unless index
+
+          record = records[index].merge("status" => "archived")
+          records[index] = record
+        end
+        record
+      end
+
+      private
+
+      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 store 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(records) + "\n")
+        end
+      end
+    end
+  end
+end

data/lib/kward/workers/tool_policy.rb

@@ -0,0 +1,23 @@
+module Kward
+  module Workers
+    # Tool allowlists for worker roles.
+    module ToolPolicy
+      READ_ONLY_TOOLS = %w[list_directory read_file code_search summarize_file_structure retrieve_tool_output web_search fetch_content fetch_raw read_skill].freeze
+
+      module_function
+
+      def allowed_tool_names(role)
+        case role.to_s
+        when "request", "read_only"
+          READ_ONLY_TOOLS
+        else
+          nil
+        end
+      end
+
+      def write_capable?(role)
+        allowed_tool_names(role).nil?
+      end
+    end
+  end
+end