kward 0.71.0 → 0.73.0

data/lib/kward/tools/context_for_task.rb

@@ -0,0 +1,204 @@
+require "pathname"
+require_relative "../workspace"
+require_relative "base"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Builds a compact, task-shaped bundle from likely workspace files.
+    class ContextForTask < Base
+      DEFAULT_BUDGET = 4_000
+      MAX_BUDGET = 20_000
+      MAX_FILES = 8
+      MAX_MATCHES_PER_FILE = 8
+      DEFAULT_EXTENSIONS = %w[.rb .js .jsx .ts .tsx .py .go .rs .java .cs .cpp .c .h .hpp .md .yml .yaml .json .toml].freeze
+      SKIP_DIRECTORIES = %w[.git .yardoc _yardoc node_modules vendor tmp log coverage dist build .bundle].freeze
+
+      # Builds the tool schema and stores the execution dependency.
+      def initialize(workspace:)
+        @workspace = workspace
+        super(
+          "context_for_task",
+          "Build focused workspace context for a task from outlines and matching excerpts within a byte budget.",
+          properties: {
+            budget: { type: "integer", description: "Approximate byte budget for the returned context. Default 4000, maximum 20000." },
+            paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative files or directories to focus." },
+            task: { type: "string", description: "Task or question to gather context for." }
+          },
+          required: ["task"]
+        )
+      end
+
+      # Executes focused context retrieval.
+      def call(args, _conversation, cancellation: nil)
+        cancellation&.raise_if_cancelled!
+        task = argument(args, :task, "").to_s.strip
+        return "Error: task is required" if task.empty?
+
+        budget = normalized_budget(argument(args, :budget))
+        return budget if budget.is_a?(String)
+
+        focus_paths = Array(argument(args, :paths, [])).map(&:to_s).reject(&:empty?)
+        files = candidate_files(focus_paths, cancellation: cancellation)
+        return "No readable candidate files found for focused context." if files.empty?
+
+        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}"
+      end
+
+      private
+
+      def normalized_budget(value)
+        return DEFAULT_BUDGET if value.nil?
+
+        budget = value.to_i
+        return "Error: budget must be positive" unless budget.positive?
+
+        [budget, MAX_BUDGET].min
+      end
+
+      def candidate_files(paths, cancellation:)
+        roots = paths.empty? ? [@workspace.root.to_s] : paths.map { |path| @workspace.resolved_path(path) }
+        files = roots.flat_map do |path|
+          cancellation&.raise_if_cancelled!
+          File.directory?(path) ? files_under(path, cancellation: cancellation) : [path]
+        end
+        files.uniq.select { |path| readable_context_file?(path) }.first(MAX_FILES * 8)
+      end
+
+      def files_under(root, cancellation:)
+        files = []
+        stack = [root]
+        until stack.empty? || files.length >= MAX_FILES * 8
+          cancellation&.raise_if_cancelled!
+          current = stack.pop
+          next if skipped_directory?(current)
+
+          entries = Dir.children(current).sort.map { |entry| File.join(current, entry) }
+          entries.each do |entry|
+            if File.directory?(entry)
+              stack << entry
+            else
+              files << entry if readable_context_file?(entry)
+            end
+          end
+        end
+        files
+      end
+
+      def readable_context_file?(path)
+        return false unless File.file?(path)
+        return false if File.size(path) > Workspace::MAX_FILE_BYTES
+        return false unless DEFAULT_EXTENSIONS.include?(File.extname(path)) || File.basename(path) == "Gemfile"
+
+        sample = File.open(path, "rb") { |file| file.read(4096).to_s }
+        !sample.include?("\x00")
+      rescue Errno::ENOENT, Errno::EACCES
+        false
+      end
+
+      def skipped_directory?(path)
+        SKIP_DIRECTORIES.include?(File.basename(path))
+      end
+
+      def search_terms(task)
+        task.scan(/[A-Za-z_][A-Za-z0-9_]{2,}/).map(&:downcase).reject { |term| stopword?(term) }.uniq.first(20)
+      end
+
+      def stopword?(term)
+        %w[the and for with from this that into when where what why how fix add update change implement review debug explain failing failure error issue].include?(term)
+      end
+
+      def rank_files(files, terms)
+        scored = files.map do |path|
+          content = File.read(path)
+          relative = relative_path(path)
+          score = score_file(relative, content, terms)
+          { path: path, relative: relative, content: content, score: score }
+        rescue Errno::ENOENT, Errno::EACCES
+          nil
+        end.compact
+        filtered = terms.empty? ? scored : scored.select { |file| file[:score].positive? }
+        filtered.sort_by { |file| [-file[:score], file[:relative]] }.first(MAX_FILES)
+      end
+
+      def score_file(relative, content, terms)
+        haystack = "#{relative}\n#{content}".downcase
+        terms.sum { |term| haystack.scan(term).length } + (terms.any? { |term| relative.downcase.include?(term) } ? 5 : 0)
+      end
+
+      def render_context(task:, budget:, terms:, ranked:, cancellation:)
+        lines = ["# Focused context", "- Task: #{task}", "- Budget: #{budget} bytes", "- Search terms: #{terms.empty? ? '(none)' : terms.join(', ')}", ""]
+        used = lines.join("\n").bytesize
+
+        ranked.each do |file|
+          cancellation&.raise_if_cancelled!
+          section = file_section(file, terms)
+          break if used + section.bytesize > budget && lines.length > 5
+
+          if used + section.bytesize > budget
+            remaining = budget - used
+            break if remaining < 200
+
+            section = section.byteslice(0, remaining).to_s.scrub << "\n[Context budget reached.]"
+          end
+          lines << section
+          used += section.bytesize
+        end
+
+        lines.join("\n")
+      end
+
+      def file_section(file, terms)
+        outline = @workspace.summarize_file_structure(file[:relative])
+        matches = matching_excerpt(file[:content], terms)
+        parts = ["## #{file[:relative]}", "- Score: #{file[:score]}"]
+        parts << outline unless outline.start_with?("No recognizable source structure")
+        parts << matches unless matches.empty?
+        parts.join("\n") << "\n"
+      end
+
+      def matching_excerpt(content, terms)
+        return "" if terms.empty?
+
+        lines = content.split("\n", -1)
+        indexes = matching_indexes(lines, terms)
+        return "" if indexes.empty?
+
+        selected = indexes.flat_map { |index| ([index - 2, 0].max..[index + 2, lines.length - 1].min).to_a }.uniq.sort
+        render_excerpt(lines, selected)
+      end
+
+      def matching_indexes(lines, terms)
+        indexes = []
+        lines.each_with_index do |line, index|
+          lower = line.downcase
+          indexes << index if terms.any? { |term| lower.include?(term) }
+          break if indexes.length >= MAX_MATCHES_PER_FILE
+        end
+        indexes
+      end
+
+      def render_excerpt(lines, selected)
+        output = ["### Matching excerpts"]
+        previous = nil
+        selected.each do |index|
+          output << "..." if previous && index > previous + 1
+          output << "%4d: %s" % [index + 1, lines[index]]
+          previous = index
+        end
+        output.join("\n")
+      end
+
+      def relative_path(path)
+        Pathname.new(path).relative_path_from(@workspace.root).to_s
+      end
+    end
+  end
+end

data/lib/kward/tools/read_file.rb

@@ -11,11 +11,13 @@ module Kward
         @workspace = workspace
         super(
           "read_file",
-          "Read a workspace text file. Output is capped; use offset/limit to continue.",
+          "Read a workspace text file. Output is capped; use offset/limit or mode to control context budget.",
           properties: {
             path: { type: "string", description: "Workspace-relative path." },
-            offset: { type: "integer", description: "1-indexed start line." },
-            limit: { type: "integer", description: "Maximum lines to return." }
+            limit: { type: "integer", description: "Maximum lines to return." },
+            max_bytes: { type: "integer", description: "Optional byte budget for this read, capped by Kward's workspace read limit." },
+            mode: { type: "string", enum: %w[preview outline range full], description: "Context mode. preview returns a short slice, outline returns source declarations, range reads offset/limit, full reads until Kward's cap." },
+            offset: { type: "integer", description: "1-indexed start line." }
           },
           required: ["path"]
         )
@@ -26,7 +28,9 @@ module Kward
         path = argument(args, :path, "")
         offset = argument(args, :offset)
         limit = argument(args, :limit)
-        content = @workspace.read_file(path, offset: offset, limit: limit)
+        mode = argument(args, :mode)
+        max_bytes = argument(args, :max_bytes)
+        content = @workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
         conversation.mark_read(@workspace.resolved_path(path)) unless content.start_with?("Error:")
         content
       end

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.73.0"
 end

data/lib/kward/workers/git_guard.rb

@@ -0,0 +1,93 @@
+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
+
+      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
+        def success?
+          success
+        end
+
+        def output
+          [stdout, stderr].compact.reject(&:empty?).join("\n")
+        end
+      end
+
+      def success?(*args)
+        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)
+      rescue Errno::ENOENT
+        Result.new(success: false, stdout: "", stderr: "git executable not found")
+      end
+    end
+  end
+end

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/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