kward 0.76.0 → 0.77.0

data/lib/kward/workers/manager.rb

@@ -1,328 +0,0 @@
-require "timeout"
-require_relative "../agent"
-require_relative "../cancellation"
-require_relative "../conversation"
-require_relative "../hooks"
-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 }, hook_manager: nil, hook_context: nil)
-        @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
-        @hook_manager = hook_manager
-        @hook_context = hook_context
-        @workers = {}
-        @mutex = Mutex.new
-      end
-
-      def start(role:, prompt:, title: nil, id: nil)
-        worker = build_worker(role: role, prompt: prompt, title: title, id: id)
-        run_blocking_hook("worker_job_create", worker)
-        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)
-        run_blocking_hook("worker_job_start_before", worker)
-        update_status(worker, "running")
-        run_hook("worker_job_start_after", worker)
-        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,
-          hook_manager: @hook_manager,
-          hook_context: @hook_context
-        )
-        agent = Agent.new(client: @client_factory.call, tool_registry: registry, conversation: conversation, hook_manager: @hook_manager, hook_context: @hook_context)
-        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: "")
-        run_hook("worker_job_ready_for_review", worker)
-      rescue WorkerTimeoutError
-        update_status(worker, "failed", error: "Worker timed out after #{@timeout_seconds} seconds")
-        run_hook("worker_job_failed", worker, 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)
-        run_hook("worker_job_failed", worker, error: e.message)
-      ensure
-        release_worker_writer(worker)
-      end
-
-      def run_blocking_hook(name, worker, payload = {})
-        result = run_hook(name, worker, payload)
-        return result unless result && !result.allowed?
-
-        raise HookDenied, result.decision.message || "Worker lifecycle hook #{name} blocked the job"
-      end
-
-      def run_hook(name, worker, payload = {})
-        return unless @hook_manager
-
-        @hook_manager.run(Hooks::Event.new(
-          name: name,
-          workspace: { root: worker.workspace_root },
-          payload: worker_payload(worker).merge(payload)
-        ), context: @hook_context)
-      end
-
-      HookDenied = Class.new(StandardError)
-
-      def worker_payload(worker)
-        {
-          worker_id: worker.id,
-          role: worker.role,
-          title: worker.title,
-          status: worker.status,
-          session_path: worker.session&.path
-        }.compact
-      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

@@ -1,166 +0,0 @@
-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

@@ -1,112 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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