kward 0.70.0 → 0.72.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/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

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,7 @@
+require_relative "workers/git_guard"
+require_relative "workers/live_view"
+require_relative "workers/manager"
+require_relative "workers/store"
+require_relative "workers/tool_policy"
+require_relative "workers/write_lock"
+require_relative "workers/worker"