kward 0.76.0 → 0.77.0

data/lib/kward/session_store.rb

@@ -309,11 +309,10 @@ module Kward
     # Lists recent non-empty sessions for this workspace.
     #
     # @param limit [Integer, nil] maximum number of sessions, or nil for all
-    # @param keep_empty_path [String, nil] empty session path to keep visible
+    # @param keep_empty_path [String, Array<String>, nil] live empty session path(s) to preserve while omitting them from results
     # @return [Array<SessionInfo>] newest sessions first
     def recent(limit: 20, keep_empty_path: nil)
-      sessions = recent_sessions(keep_empty_path: keep_empty_path)
-      limit ? sessions.first(limit) : sessions
+      recent_sessions(limit: limit, keep_empty_path: keep_empty_path)
     end
 
     # Persists the last active session pointer for workspace auto-resume.
@@ -344,9 +343,7 @@ module Kward
     #
     # @return [Array<SessionInfo>] recent sessions with tree depth fields
     def recent_tree(limit: 20, keep_empty_path: nil)
-      sessions = recent_sessions(keep_empty_path: keep_empty_path)
-      sessions = sessions.first(limit) if limit
-      decorate_tree(sessions)
+      decorate_tree(recent_sessions(limit: limit, keep_empty_path: keep_empty_path))
     end
 
     # Deletes an empty unnamed session file.
@@ -770,20 +767,30 @@ module Kward
       nil
     end
 
-    def recent_sessions(keep_empty_path: nil)
-      keep_empty_path = File.expand_path(keep_empty_path) unless keep_empty_path.to_s.empty?
-      Dir.glob(File.join(session_dir, "*.jsonl")).filter_map do |path|
-        info = session_info(path)
-        next unless info
-        next if delete_empty_unnamed_session_info(info, keep_empty_path: keep_empty_path)
+    def recent_sessions(limit: nil, keep_empty_path: nil)
+      keep_empty_paths = Array(keep_empty_path).filter_map do |path|
+        File.expand_path(path) unless path.to_s.empty?
+      end
+      paths = Dir.glob(File.join(session_dir, "*.jsonl")).sort_by { |path| session_file_mtime(path) }.reverse
+      sessions = []
+
+      paths.each do |path|
+        if limit.nil? || sessions.length < limit
+          info = session_info(path)
+          next unless info
+          next if delete_empty_unnamed_session_info(info, keep_empty_paths: keep_empty_paths)
 
-        info
-      end.sort_by { |info| info.modified_at || Time.at(0) }.reverse
+          sessions << info
+        else
+          delete_empty_unnamed_session_path(path, keep_empty_paths: keep_empty_paths)
+        end
+      end
+      sessions
     end
 
-    def delete_empty_unnamed_session_info(info, keep_empty_path: nil)
+    def delete_empty_unnamed_session_info(info, keep_empty_paths: [])
       return false unless info.name.to_s.strip.empty? && info.message_count.to_i.zero?
-      return true if keep_empty_path && File.expand_path(info.path) == keep_empty_path
+      return true if keep_empty_paths.include?(File.expand_path(info.path))
 
       File.delete(info.path)
       true
@@ -791,6 +798,38 @@ module Kward
       false
     end
 
+    def session_file_mtime(path)
+      File.mtime(path)
+    rescue StandardError
+      Time.at(0)
+    end
+
+    def delete_empty_unnamed_session_path(path, keep_empty_paths: [])
+      return false unless empty_unnamed_session_path?(path)
+      return true if keep_empty_paths.include?(File.expand_path(path))
+
+      File.delete(path)
+      true
+    rescue StandardError
+      false
+    end
+
+    def empty_unnamed_session_path?(path)
+      header = false
+      name = nil
+      File.foreach(path) do |line|
+        record = JSON.parse(line)
+        header = true if record["type"] == "session" && !record["id"].to_s.empty?
+        name = record["name"] if record["type"] == "session_info" && record.key?("name")
+        next unless record["type"] == "message"
+
+        return false if ["user", "assistant", "tool"].include?(message_role(record["message"] || {}))
+      end
+      header && name.to_s.strip.empty?
+    rescue JSON::ParserError
+      false
+    end
+
     def decorate_tree(sessions)
       by_parent = Hash.new { |hash, key| hash[key] = [] }
       ids = sessions.map(&:id).to_h { |id| [id, true] }

data/lib/kward/skills/registry.rb

@@ -4,7 +4,13 @@ require "pathname"
 module Kward
   # Skill discovery and metadata parsing from configured skill folders.
   module Skills
-    # Parsed skill metadata and instruction path.
+    # Discovers Agent Skills and reads their bounded instruction resources.
+    #
+    # Project sources are included only when the caller marks them trusted. If
+    # duplicate skill names exist, the first source in documented precedence
+    # order wins.
+    #
+    # @api public
     class Registry
       SkillSource = Struct.new(:root, :label, :scope, :precedence, keyword_init: true)
 
@@ -18,6 +24,10 @@ module Kward
         @inside_directory = inside_directory
       end
 
+      # Returns discovered, validated skills in precedence order.
+      #
+      # @return [Array<ConfigFiles::Skill>]
+      # @api public
       def skills
         seen = {}
         skill_sources.flat_map do |source|
@@ -39,6 +49,16 @@ module Kward
         []
       end
 
+      # Reads a skill's main instructions or a bounded relative resource.
+      #
+      # Absolute paths, paths escaping the skill folder, missing files, and files
+      # above the configured size limit return user-facing error strings.
+      #
+      # @param name [String, #to_s] discovered skill name
+      # @param relative_path [String, nil] file relative to the skill directory;
+      #   defaults to `SKILL.md`
+      # @return [String] skill content or an error message
+      # @api public
       def read_skill_file(name, relative_path = nil)
         skill = skills.find { |candidate| candidate.name == name.to_s }
         return "Error: unknown skill: #{name}" unless skill

data/lib/kward/tools/base.rb

@@ -3,11 +3,22 @@ module Kward
   # Model-callable tool wrappers and their argument schemas.
   module Tools
     # Base class for model-callable tools and their JSON schemas.
+    #
+    # Concrete built-in tools initialize this class with their model-facing name,
+    # description, and strict argument schema, then implement `call` to perform
+    # the operation. Tool execution is coordinated by {Kward::ToolRegistry}.
+    #
+    # @api public
     class Base
       # @return [String] function name exposed to the model
       attr_reader :name
 
       # Creates a tool schema definition shared by all concrete tool wrappers.
+      #
+      # @param name [String] function name exposed to the model
+      # @param description [String] model-facing description of the operation
+      # @param properties [Hash] JSON Schema properties keyed by argument name
+      # @param required [Array<String, Symbol>] required argument names
       def initialize(name, description, properties: {}, required: [])
         @name = name
         @description = description
@@ -16,6 +27,9 @@ module Kward
       end
 
       # Returns the strict JSON schema advertised to model providers.
+      #
+      # @return [Hash] function schema with additional properties disabled
+      # @api public
       def schema
         {
           type: "function",

data/lib/kward/tools/registry.rb

@@ -46,11 +46,12 @@ module Kward
   # individual tools, and legacy-compatible shapes are accepted where already
   # supported. Required fields and invalid required values should still return
   # explicit tool errors.
+  # @api public
   class ToolRegistry
     # 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, :writer_id
+    attr_reader :schemas
 
     # Builds tool objects and the schema list for the current frontend/config.
     #
@@ -63,7 +64,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, allowed_tool_names: nil, write_lock: nil, writer_id: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, hook_manager: nil, hook_context: nil)
+    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, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, hook_manager: nil, hook_context: nil)
       @workspace = workspace
       @prompt = prompt
       @web_search = web_search
@@ -73,8 +74,6 @@ module Kward
       @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
@@ -115,8 +114,6 @@ module Kward
                              hook_denied_content(before_tool, "tool call denied: #{name}")
                            elsif before_tool.approval_required? && hook_approval_denied?(before_tool, tool_call, name, args, cancellation)
                              hook_denied_content(before_tool, "tool call approval denied: #{name}")
-                           elsif mutation_tool?(name) && !write_lock_owned?
-                             "Workspace write denied: another worker owns the write lock."
                            elsif tool_approval_denied?(tool_call, name, args, cancellation)
                              "Declined: tool execution denied by user: #{name}"
                            else
@@ -148,6 +145,14 @@ module Kward
       model_content
     end
 
+    # Returns frontend discovery metadata for a tool name.
+    #
+    # Unknown names return metadata with an unknown source rather than raising,
+    # which lets RPC clients render restored or unsupported tool calls safely.
+    #
+    # @param name [String, #to_s] exposed tool name
+    # @return [Hash] source, display name, and optional MCP identity
+    # @api public
     def metadata_for(name)
       tool = @tools[name.to_s]
       return unknown_tool_metadata(name) unless tool
@@ -415,22 +420,12 @@ module Kward
       (metadata[:source] || metadata["source"]).to_s == "mcp"
     end
 
-    def mutation_tool?(name)
-      ToolCall.write_lock_required?(name)
-    end
-
     def tool_approval_denied?(tool_call, name, args, cancellation)
       return false unless @tool_approval
 
       @tool_approval.call(tool_call: tool_call, name: name, args: args, cancellation: cancellation) == false
     end
 
-    def write_lock_owned?
-      return true unless @write_lock
-
-      @write_lock.owned_by?(@writer_id)
-    end
-
     def build_tools
       tools = all_tools
       tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names

data/lib/kward/tools/search/code.rb

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require "fileutils"
 require "json"
 require "net/http"

data/lib/kward/tools/search/web.rb

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require "json"
 require "net/http"
 require "nokogiri"

data/lib/kward/tools/tool_call.rb

@@ -67,10 +67,6 @@ 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

data/lib/kward/transcript_export.rb

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require_relative "markdown_transcript"
 
 # Namespace for the Kward CLI agent runtime.

data/lib/kward/version.rb

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

data/templates/default/kward_navigation.rb

@@ -9,6 +9,7 @@ module KwardDocsNavigationData
         ["Usage", "file.usage.html"],
         ["Configuration", "file.configuration.html"],
         ["Authentication", "file.authentication.html"],
+        ["Security and trust", "file.security.html"],
         ["Troubleshooting", "file.troubleshooting.html"]
       ]
     ],
@@ -16,10 +17,12 @@ module KwardDocsNavigationData
       "Feature guides",
       [
         ["Sessions", "file.session-management.html"],
+        ["Interactive composer", "file.composer.html"],
         ["Tabs", "file.tabs.html"],
         ["Memory", "file.memory.html"],
         ["Personas", "file.personas.html"],
-        ["Skills", "file.skills.html"]
+        ["Skills", "file.skills.html"],
+        ["Pan mode", "file.pan.html"]
       ]
     ],
     [
@@ -45,6 +48,7 @@ module KwardDocsNavigationData
     [
       "Integrate",
       [
+        ["MCP servers", "file.mcp.html"],
         ["RPC protocol", "file.rpc.html"],
         ["Releasing", "file.releasing.html"]
       ]

data/templates/default/layout/html/layout.erb

@@ -110,7 +110,6 @@
           <article><strong>⌘</strong><h2>Project-aware agent loop</h2><p>Inspect, reason, patch, verify.</p></article>
           <article><strong>▤</strong><h2>Unix filter mode</h2><p>Pipe diffs, logs, and code through Kward.</p></article>
           <article><strong>▰</strong><h2>Branchable sessions</h2><p>Resume, rewind, fork, compact, export.</p></article>
-          <article><strong>›_</strong><h2>Worker pipelines</h2><p>Queue focused agent tasks from the TUI.</p></article>
           <article><strong>◎</strong><h2>Live source intelligence</h2><p>Search the web and read public repos.</p></article>
           <article><strong>✣</strong><h2>Ruby-native extensions</h2><p>Shape Kward with plugins, skills, and prompts.</p></article>
         </section>
@@ -137,7 +136,6 @@
             <li>Review diffs, stage files, and commit changes from the integrated Git workflow.</li>
             <li>Pipe diffs, logs, code, and generated text through Kward as a Unix filter.</li>
             <li>Organize long-running work with tabs, sessions, rewind, forks, compaction, and exports.</li>
-            <li>Dispatch worker tasks, leave them running, review the results later.</li>
             <li>Ground answers with live web search and public source repositories before guessing.</li>
             <li>Shape Kward with memory, skills, prompts, personas, and trusted Ruby plugins.</li>
             <li>Build custom UIs on top of Kward’s JSON-RPC backend.</li>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kward
 version: !ruby/object:Gem::Version
-  version: 0.76.0
+  version: 0.77.0
 platform: ruby
 authors:
 - Kai Wood
@@ -129,6 +129,7 @@ files:
 - doc/api.md
 - doc/authentication.md
 - doc/code-search.md
+- doc/composer.md
 - doc/configuration.md
 - doc/context-budgeting.md
 - doc/context-tools.md
@@ -140,10 +141,12 @@ files:
 - doc/lifecycle-hooks.md
 - doc/mcp.md
 - doc/memory.md
+- doc/pan.md
 - doc/personas.md
 - doc/plugins.md
 - doc/releasing.md
 - doc/rpc.md
+- doc/security.md
 - doc/session-management.md
 - doc/shell.md
 - doc/skills.md
@@ -234,6 +237,7 @@ files:
 - lib/kward/model/stream_parser.rb
 - lib/kward/openrouter_model_cache.rb
 - lib/kward/pan/index.html.erb
+- lib/kward/pan/kward_logo.png
 - lib/kward/pan/server.rb
 - lib/kward/path_guard.rb
 - lib/kward/plugin_registry.rb
@@ -348,17 +352,6 @@ files:
 - lib/kward/transcript_export.rb
 - lib/kward/update_check.rb
 - lib/kward/version.rb
-- lib/kward/workers.rb
-- lib/kward/workers/git_guard.rb
-- lib/kward/workers/job.rb
-- lib/kward/workers/live_view.rb
-- lib/kward/workers/manager.rb
-- lib/kward/workers/queue_runner.rb
-- lib/kward/workers/queue_store.rb
-- lib/kward/workers/store.rb
-- lib/kward/workers/tool_policy.rb
-- lib/kward/workers/worker.rb
-- lib/kward/workers/write_lock.rb
 - lib/kward/workspace.rb
 - lib/main.rb
 - templates/default/fulldoc/html/css/kward.css

data/lib/kward/workers/git_guard.rb

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

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

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