kward 0.71.0 → 0.72.0

data/lib/kward/tools/registry.rb

@@ -2,6 +2,8 @@ require_relative "../config_files"
 require_relative "../conversation"
 require_relative "ask_user_question"
 require_relative "code_search"
+require_relative "context_budget_stats"
+require_relative "context_for_task"
 require_relative "edit_file"
 require_relative "fetch_content"
 require_relative "fetch_raw"
@@ -45,7 +47,7 @@ module Kward
     # Tool schemas advertised to the model for the current frontend and config.
     #
     # @return [Array<Hash>] tool schemas currently advertised to the model
-    attr_reader :schemas
+    attr_reader :schemas, :writer_id
 
     # Builds tool objects and the schema list for the current frontend/config.
     #
@@ -58,7 +60,7 @@ module Kward
     # @param web_search_enabled [Boolean, nil] override for web search exposure
     # @param skills [Array<ConfigFiles::Skill>, nil] override discovered skills
     # @param ask_user_question_enabled [Boolean, nil] override question exposure
-    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new)
+    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, write_lock: nil, writer_id: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil)
       @workspace = workspace
       @prompt = prompt
       @web_search = web_search
@@ -67,8 +69,12 @@ module Kward
       @skills = skills
       @web_search_enabled = web_search_enabled
       @ask_user_question_enabled = ask_user_question_enabled
+      @allowed_tool_names = allowed_tool_names&.map(&:to_s)
+      @write_lock = write_lock
+      @writer_id = writer_id
       @tool_output_compactor = tool_output_compactor
       @telemetry_logger = telemetry_logger
+      @context_budget_meter = context_budget_meter
       @tools = build_tools.freeze
       @schemas = build_schema_tools.map(&:schema).freeze
     end
@@ -89,34 +95,60 @@ module Kward
       args = ToolCall.arguments(tool_call)
       tool = @tools[name]
 
-      content = if tool
-                  tool.call(args, conversation, cancellation: cancellation)
-                else
-                  "Unknown tool: #{name}"
-                end
-      content = Conversation.normalize_tool_content(content)
-      duplicate_id = conversation.tool_output_artifact_id_for(tool_name: name, content: content)
-      if conversation.tool_output_artifacts.key?(duplicate_id)
+      original_content = if tool
+                           if mutation_tool?(name) && !write_lock_owned?
+                             "Workspace write denied: another worker owns the write lock."
+                           else
+                             tool.call(args, conversation, cancellation: cancellation)
+                           end
+                         else
+                           "Unknown tool: #{name}"
+                         end
+      original_content = Conversation.normalize_tool_content(original_content)
+      duplicate_id = conversation.tool_output_artifact_id_for(tool_name: name, content: original_content)
+      content = original_content
+      if reusable_duplicate_output?(name) && conversation.tool_output_artifacts.key?(duplicate_id)
         content = "[Same as previous tool output #{duplicate_id}; not repeated. Use retrieve_tool_output to inspect it.]"
       end
 
       artifact_id = nil
       model_content = @tool_output_compactor.compact(name, content) do
-        artifact_id ||= conversation.store_tool_output_artifact(tool_name: name, content: content)
+        artifact_id ||= conversation.store_tool_output_artifact(tool_name: name, content: original_content)
       end
-      log_tool_output_compaction(name, artifact_id: artifact_id, before: content, after: model_content) if model_content != content
+      record_context_budget(conversation, name, before: original_content, after: model_content)
+      log_tool_output_compaction(name, artifact_id: artifact_id, before: original_content, after: model_content) if model_content != original_content
       conversation.append_tool(
         tool_call_id: tool_call["id"] || tool_call[:id],
         name: name,
         content: model_content
       )
-      conversation.append_tool_execution(tool_call: tool_call, content: content)
+      conversation.append_tool_execution(tool_call: tool_call, content: original_content)
 
       model_content
     end
 
     private
 
+    def record_context_budget(conversation, name, before:, after:)
+      meter = conversation.respond_to?(:context_budget_meter) ? conversation.context_budget_meter : @context_budget_meter
+      return unless meter
+      return if name.to_s == "context_budget_stats"
+
+      saved = meter.record(tool_name: name, original_bytes: before.bytesize, returned_bytes: after.bytesize)
+      @telemetry_logger.log(
+        "compaction",
+        "context_budget",
+        "tool_name" => name,
+        "bytes_before" => before.bytesize,
+        "bytes_after" => after.bytesize,
+        "bytes_saved" => saved
+      )
+    end
+
+    def reusable_duplicate_output?(name)
+      name.to_s != "read_skill"
+    end
+
     def log_tool_output_compaction(name, artifact_id:, before:, after:)
       @telemetry_logger.log(
         "compaction",
@@ -129,18 +161,30 @@ module Kward
       )
     end
 
+    def mutation_tool?(name)
+      ToolCall.write_lock_required?(name)
+    end
+
+    def write_lock_owned?
+      return true unless @write_lock
+
+      @write_lock.owned_by?(@writer_id)
+    end
+
     def build_tools
-      all_tools.to_h { |tool| [tool.name, tool] }
+      tools = all_tools
+      tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names
+      tools.to_h { |tool| [tool.name, tool] }
     end
 
     def build_schema_tools
       tools = @tools.values_at(
-        "list_directory", "read_file", "write_file", "edit_file", "run_shell_command", "code_search", "summarize_file_structure", "retrieve_tool_output"
+        "list_directory", "read_file", "write_file", "edit_file", "run_shell_command", "code_search", "summarize_file_structure", "context_for_task", "context_budget_stats", "retrieve_tool_output"
       )
       tools.concat(@tools.values_at("web_search", "fetch_content", "fetch_raw")) if web_search_available?
       tools << @tools["read_skill"] if skills_available?
       tools << @tools["ask_user_question"] if ask_user_question_available?
-      tools
+      tools.compact
     end
 
     def all_tools
@@ -162,6 +206,8 @@ module Kward
         Tools::RunShellCommand.new(workspace: @workspace),
         Tools::CodeSearch.new(code_search: @code_search),
         Tools::SummarizeFileStructure.new(workspace: @workspace),
+        Tools::ContextForTask.new(workspace: @workspace),
+        Tools::ContextBudgetStats.new(context_budget_meter: @context_budget_meter),
         Tools::RetrieveToolOutput.new
       ]
     end

data/lib/kward/tools/tool_call.rb

@@ -18,6 +18,8 @@ module Kward
       "list_directory" => "list_directory",
       "code_search" => "code_search",
       "summarize_file_structure" => "summarize_file_structure",
+      "context_for_task" => "context_for_task",
+      "context_budget_stats" => "context_budget_stats",
       "retrieve_tool_output" => "retrieve_tool_output",
       "web_search" => "web_search",
       "fetch_content" => "fetch_content",
@@ -65,6 +67,14 @@ module Kward
       TOOL_NAME_MAP[name.to_s]
     end
 
+    def write_lock_required?(name)
+      %w[edit_file write_file run_shell_command edit write bash].include?(name.to_s)
+    end
+
+    def file_change_tool?(name)
+      %w[edit_file write_file edit write].include?(name.to_s)
+    end
+
     # Converts provider argument payloads into hashes.
     #
     # Providers normally send JSON strings, while tests and compatibility callers

data/lib/kward/version.rb

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

data/lib/kward/workers/git_guard.rb

@@ -0,0 +1,68 @@
+require "open3"
+
+module Kward
+  module Workers
+    # Small git boundary used by write-lane workers to keep implementation work isolated.
+    class GitGuard
+      def initialize(root: Dir.pwd)
+        @root = root.to_s
+      end
+
+      def repository?
+        success?("rev-parse", "--is-inside-work-tree")
+      end
+
+      def clean?
+        return true unless repository?
+
+        status.empty?
+      end
+
+      def dirty?
+        !clean?
+      end
+
+      def status
+        run("status", "--porcelain").stdout
+      end
+
+      def head
+        result = run("rev-parse", "--verify", "HEAD")
+        result.success? ? result.stdout.strip : nil
+      end
+
+      def commit_all(message)
+        add = run("add", "-A")
+        return Result.new(success: false, stdout: add.stdout, stderr: add.stderr) unless add.success?
+
+        commit = run("commit", "-m", message)
+        return Result.new(success: false, stdout: commit.stdout, stderr: commit.stderr) unless commit.success?
+
+        Result.new(success: true, stdout: commit.stdout, stderr: commit.stderr, commit: head)
+      end
+
+      private
+
+      Result = Struct.new(:success, :stdout, :stderr, :commit, keyword_init: true) do
+        def success?
+          success
+        end
+
+        def output
+          [stdout, stderr].compact.reject(&:empty?).join("\n")
+        end
+      end
+
+      def success?(*args)
+        run(*args).success?
+      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)
+      rescue Errno::ENOENT
+        Result.new(success: false, stdout: "", stderr: "git executable not found")
+      end
+    end
+  end
+end

data/lib/kward/workers/live_view.rb

@@ -0,0 +1,49 @@
+module Kward
+  module Workers
+    # Drains a running worker's accumulated event history into a frontend renderer.
+    class LiveView
+      FINISHED_STATUSES = %w[ready failed cancelled archived].freeze
+
+      def initialize(worker:, agent:, renderer:, poll_interval: 0.05)
+        @worker = worker
+        @agent = agent
+        @renderer = renderer
+        @poll_interval = poll_interval
+        @seen_events = worker.event_history.length
+        @stop = false
+        @thread = nil
+      end
+
+      attr_reader :worker, :agent
+
+      def start
+        @thread = Thread.new { run }
+        @thread.report_on_exception = false
+        self
+      end
+
+      def stop
+        @stop = true
+        @thread&.join(0.2)
+      end
+
+      private
+
+      def run
+        until @stop
+          events = @worker.event_history[@seen_events..] || []
+          events.each { |event| @renderer.call(event, @agent) }
+          @seen_events += events.length
+          @renderer.call(:flush, @agent) if finished?
+          break if finished?
+
+          sleep @poll_interval
+        end
+      end
+
+      def finished?
+        FINISHED_STATUSES.include?(@worker.status)
+      end
+    end
+  end
+end

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