kward 0.78.0 → 0.80.0

data/lib/kward/sandbox/macos_seatbelt_runner.rb

@@ -0,0 +1,96 @@
+require "fileutils"
+require "tmpdir"
+require_relative "command_runner"
+require_relative "environment"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Runs a command under macOS Seatbelt. This backend deliberately constrains
+    # writes and child networking first; host-process and plugin access remain
+    # outside the command worker boundary.
+    class MacOSSeatbeltRunner < CommandRunner
+      EXECUTABLE = "/usr/bin/sandbox-exec".freeze
+      PROTECTED_READ_DIRECTORIES = %w[.aws .gnupg .kward .ssh .config/gcloud .config/gh].freeze
+
+      def self.capabilities(platform: RUBY_PLATFORM)
+        available = platform.to_s.include?("darwin") && File.executable?(EXECUTABLE)
+        return Capabilities.new(available: true, filesystem_enforced: true, child_network_enforced: true, backend: "macos_seatbelt") if available
+
+        Capabilities.new(
+          available: false,
+          filesystem_enforced: false,
+          child_network_enforced: false,
+          backend: "macos_seatbelt",
+          reason: "#{EXECUTABLE} is unavailable"
+        )
+      end
+
+      def initialize(policy:, capabilities: self.class.capabilities)
+        raise ArgumentError, "macOS Seatbelt is unavailable: #{capabilities.reason}" unless capabilities.available?
+
+        super
+      end
+
+      def run(command, cwd:, timeout_seconds:, max_output_bytes:, cancellation: nil, &block)
+        temporary_root = Dir.mktmpdir("kward-sandbox")
+        environment = Environment.command_worker(temporary_root)
+
+        LocalCommandRunner.new(
+          timeout_seconds: timeout_seconds,
+          max_output_bytes: max_output_bytes
+        ).run(
+          *command_argv(command, cwd: cwd, temporary_root: temporary_root),
+          env: environment,
+          cwd: cwd,
+          cancellation: cancellation,
+          unsetenv_others: true,
+          &block
+        )
+      ensure
+        FileUtils.remove_entry(temporary_root) if temporary_root && File.exist?(temporary_root)
+      end
+
+      def command_argv(command, cwd:, temporary_root: nil)
+        temporary_root ||= Dir.tmpdir
+        [EXECUTABLE, "-p", profile(temporary_root), "/bin/zsh", "-lc", command.to_s]
+      end
+
+      private
+
+      def profile(temporary_root)
+        writable_roots = policy.command_writable_roots + [File.realpath(temporary_root)]
+        rules = [
+          "(version 1)",
+          "(deny default)",
+          "(allow process*)",
+          "(allow signal)",
+          "(allow file-read*)",
+          "(allow file-write-data (literal \"/dev/null\"))",
+          "(allow sysctl-read)",
+          "(allow mach-lookup)",
+          "(allow ipc-posix-shm*)",
+          "(allow user-preference-read)",
+          "(allow pseudo-tty)"
+        ]
+        rules << "(allow network*)" if policy.child_network_allowed?
+        rules.concat(writable_roots.map { |path| "(allow file-write* (subpath #{seatbelt_string(path)}))" })
+        rules.concat(protected_read_roots.map { |path| "(deny file-read* (subpath #{seatbelt_string(path)}))" })
+        rules << "(deny file-write* (subpath #{seatbelt_string(File.join(policy.workspace_root, ".git"))}))" if policy.protect_git_metadata?
+        rules.join("\n")
+      end
+
+      def protected_read_roots
+        home = ENV.fetch("HOME", Dir.home)
+        PROTECTED_READ_DIRECTORIES.map do |path|
+          root = File.join(home, path)
+          File.exist?(root) ? File.realpath(root) : root
+        end
+      end
+
+      def seatbelt_string(value)
+        %Q{"#{value.to_s.gsub(/([\\"])/, '\\\\1')}"}
+      end
+    end
+  end
+end

data/lib/kward/sandbox/passthrough_runner.rb

@@ -0,0 +1,13 @@
+require_relative "command_runner"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Preserves existing LocalCommandRunner behavior when sandboxing is off.
+    class PassthroughRunner < CommandRunner
+      def command_argv(command, cwd:)
+        [command.to_s]
+      end
+    end
+  end
+end

data/lib/kward/sandbox/policy.rb

@@ -0,0 +1,74 @@
+require "pathname"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Immutable, user-configured restrictions for a command worker.
+    class Policy
+      MODES = %w[off read_only workspace_write].freeze
+      NETWORK_MODES = %w[deny allow].freeze
+
+      attr_reader :mode, :network, :workspace_root, :writable_roots
+
+      def initialize(mode: "off", network: "deny", workspace_root:, writable_roots: [], protect_git_metadata: true)
+        @mode = normalize_mode(mode)
+        @network = normalize_network(network)
+        @workspace_root = canonical_path(workspace_root)
+        @writable_roots = normalize_writable_roots(writable_roots)
+        @protect_git_metadata = protect_git_metadata != false
+      end
+
+      def enabled?
+        mode != "off"
+      end
+
+      def read_only?
+        mode == "read_only"
+      end
+
+      def workspace_write?
+        mode == "workspace_write"
+      end
+
+      def protect_git_metadata?
+        @protect_git_metadata
+      end
+
+      def child_network_allowed?
+        network == "allow"
+      end
+
+      def command_writable_roots
+        return [] unless workspace_write?
+
+        ([workspace_root] + writable_roots).uniq
+      end
+
+      private
+
+      def normalize_mode(value)
+        mode = value.to_s
+        return mode if MODES.include?(mode)
+
+        raise ArgumentError, "sandbox mode must be one of: #{MODES.join(", ")}"
+      end
+
+      def normalize_network(value)
+        network = value.to_s
+        return network if NETWORK_MODES.include?(network)
+
+        raise ArgumentError, "sandbox network must be one of: #{NETWORK_MODES.join(", ")}"
+      end
+
+      def normalize_writable_roots(roots)
+        Array(roots).map { |root| canonical_path(root) }.uniq.reject { |root| root == workspace_root }
+      end
+
+      def canonical_path(path)
+        Pathname.new(path.to_s).realpath.to_s
+      rescue Errno::ENOENT
+        raise ArgumentError, "sandbox path does not exist: #{path}"
+      end
+    end
+  end
+end

data/lib/kward/sandbox/runner_factory.rb

@@ -0,0 +1,55 @@
+require_relative "capabilities"
+require_relative "passthrough_runner"
+require_relative "unavailable_runner"
+require_relative "macos_seatbelt_runner"
+require_relative "linux_bubblewrap_runner"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Selects the command runner that can enforce a policy on the current host.
+    module RunnerFactory
+      module_function
+
+      def build(policy, platform: RUBY_PLATFORM)
+        return PassthroughRunner.new(policy:, capabilities: off_capabilities) unless policy.enabled?
+
+        runner_class = runner_class_for(platform)
+        return UnavailableRunner.new(policy:, capabilities: unsupported_capabilities(platform)) unless runner_class
+
+        capabilities = runner_class.capabilities(platform:)
+        return UnavailableRunner.new(policy:, capabilities:) unless capabilities.available?
+
+        runner_class.new(policy:, capabilities:)
+      end
+
+      def off_capabilities
+        Capabilities.new(
+          available: true,
+          filesystem_enforced: false,
+          child_network_enforced: false,
+          backend: "off"
+        )
+      end
+
+      def unsupported_capabilities(platform)
+        Capabilities.new(
+          available: false,
+          filesystem_enforced: false,
+          child_network_enforced: false,
+          backend: "unsupported",
+          reason: "Sandboxing is unsupported on #{platform}"
+        )
+      end
+
+      def runner_class_for(platform)
+        value = platform.to_s
+        return MacOSSeatbeltRunner if value.include?("darwin")
+        return LinuxBubblewrapRunner if value.include?("linux")
+
+        nil
+      end
+      private_class_method :runner_class_for
+    end
+  end
+end

data/lib/kward/sandbox/unavailable_runner.rb

@@ -0,0 +1,21 @@
+require_relative "command_runner"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Raised when a requested sandbox cannot be enforced on this host.
+    class UnavailableError < StandardError
+    end
+
+    # Fails closed rather than running a requested sandbox policy unrestricted.
+    class UnavailableRunner < CommandRunner
+      def command_argv(command, cwd:)
+        []
+      end
+
+      def run(command, cwd:, timeout_seconds:, max_output_bytes:, cancellation: nil, &block)
+        raise UnavailableError, "Sandbox #{policy.mode} is unavailable: #{capabilities.reason}"
+      end
+    end
+  end
+end

data/lib/kward/sandbox.rb

@@ -0,0 +1,9 @@
+require_relative "sandbox/policy"
+require_relative "sandbox/capabilities"
+require_relative "sandbox/environment"
+require_relative "sandbox/command_runner"
+require_relative "sandbox/passthrough_runner"
+require_relative "sandbox/unavailable_runner"
+require_relative "sandbox/macos_seatbelt_runner"
+require_relative "sandbox/linux_bubblewrap_runner"
+require_relative "sandbox/runner_factory"

data/lib/kward/session_store.rb

@@ -29,6 +29,9 @@ module Kward
   class SessionStore
     VERSION = 2
     LAST_SESSION_FILENAME = "last_session.json"
+    NON_ACTIVITY_RECORD_TYPES = %w[session session_info system_prompt].freeze
+    RECORD_TYPE_PATTERN = /\A\{\s*"type"\s*:\s*"([^"]+)"/
+    RECORD_TIMESTAMP_PATTERN = /"timestamp"\s*:\s*"([^"]+)"/
 
     SessionInfo = Struct.new(:id, :path, :cwd, :created_at, :modified_at, :name, :first_message, :message_count, :provider, :model, :reasoning_effort, :parent_id, :parent_path, :depth, :is_last, :ancestor_continues, keyword_init: true)
 
@@ -47,6 +50,8 @@ module Kward
       attr_reader :cwd
       # @return [Time] creation timestamp used for sorting and filenames
       attr_reader :created_at
+      # @return [Time] timestamp of the latest persisted conversation activity
+      attr_reader :modified_at
       # @return [String, nil] source session id when this session was cloned or forked
       attr_reader :parent_id
       # @return [String, nil] source session path when this session was cloned or forked
@@ -57,16 +62,18 @@ module Kward
       attr_accessor :leaf_id
 
       # Creates an object for JSONL session persistence.
-      def initialize(store:, id:, path:, cwd:, created_at:, name: nil, parent_id: nil, parent_path: nil, leaf_id: nil)
+      def initialize(store:, id:, path:, cwd:, created_at:, name: nil, parent_id: nil, parent_path: nil, leaf_id: nil, modified_at: nil, system_prompt_hash: nil)
         @store = store
         @id = id
         @path = path
         @cwd = cwd
         @created_at = created_at
+        @modified_at = modified_at || created_at
         @name = name
         @parent_id = parent_id
         @parent_path = parent_path
         @leaf_id = leaf_id
+        @system_prompt_hash = system_prompt_hash
       end
 
       # Installs persistence callbacks on `conversation`.
@@ -89,6 +96,7 @@ module Kward
         record = @store.build_tree_record(@path, "message", @leaf_id, message: message)
         @leaf_id = record[:id]
         @store.append_record(@path, record)
+        mark_modified(record)
       end
 
       # Persists a compaction summary entry and makes it the active leaf.
@@ -96,26 +104,36 @@ module Kward
         record = @store.build_tree_record(@path, "compaction", @leaf_id, message: message)
         @leaf_id = record[:id]
         @store.append_record(@path, record)
+        mark_modified(record)
       end
 
       # Persists normalized tool execution metadata alongside transcript messages.
       def append_tool_execution(tool_call, content)
-        @store.append_record(@path, RPC::ToolEventNormalizer.new(tool_call, content: content).execution_record)
+        record = RPC::ToolEventNormalizer.new(tool_call, content: content).execution_record
+        @store.append_record(@path, record)
+        mark_modified(record)
       end
 
       # Persists the current system prompt as audit metadata when it changes.
       def append_system_prompt_snapshot(system_message, reason: "changed")
-        @store.append_system_prompt_snapshot(@path, system_message, reason: reason)
+        @system_prompt_hash = @store.append_system_prompt_snapshot(
+          @path,
+          system_message,
+          reason: reason,
+          latest_hash: @system_prompt_hash
+        )
       end
 
       # Persists the session memory snapshot used when the session is restored.
       def update_memory_state(session_memories:, last_retrieval: nil)
-        @store.append_record(@path, {
+        record = {
           type: "memory_state",
           timestamp: Time.now.utc.iso8601(3),
           sessionMemories: Array(session_memories),
           lastRetrieval: last_retrieval
-        })
+        }
+        @store.append_record(@path, record)
+        mark_modified(record)
       end
 
       # Persists a user-visible session name without rewriting earlier records.
@@ -131,7 +149,8 @@ module Kward
       # Moves the active leaf to an existing entry so future messages fork there.
       def branch(entry_id)
         @leaf_id = entry_id.to_s.empty? ? nil : entry_id.to_s
-        @store.append_leaf_change(@path, @leaf_id)
+        record = @store.append_leaf_change(@path, @leaf_id)
+        mark_modified(record)
       end
 
       # Clears the active leaf so the next append starts a fresh root branch.
@@ -141,7 +160,8 @@ module Kward
 
       # Persists a display label override for one tree entry.
       def append_label_change(entry_id, label)
-        @store.append_label_change(@path, entry_id, label)
+        record = @store.append_label_change(@path, entry_id, label)
+        mark_modified(record)
       end
 
       # Adds a branch-summary node under `parent_id` and selects it as the leaf.
@@ -149,6 +169,7 @@ module Kward
         record = @store.build_tree_record(@path, "branch_summary", parent_id, fromId: from_id, summary: summary, details: details || {})
         @leaf_id = record[:id]
         @store.append_record(@path, record)
+        mark_modified(record)
         record[:id]
       end
 
@@ -168,6 +189,15 @@ module Kward
       def delete_if_unused
         @store.delete_unused_session(self)
       end
+
+      private
+
+      def mark_modified(record)
+        timestamp = record[:timestamp] || record["timestamp"]
+        @modified_at = Time.iso8601(timestamp.to_s) || Time.now.utc
+      rescue ArgumentError
+        @modified_at = Time.now.utc
+      end
     end
 
     # Creates an object for JSONL session persistence.
@@ -211,7 +241,7 @@ module Kward
       end
       File.chmod(0o600, path)
 
-      Session.new(store: self, id: id, path: path, cwd: @cwd, created_at: created_at, parent_id: parent_id, parent_path: parent_path, leaf_id: nil)
+      Session.new(store: self, id: id, path: path, cwd: @cwd, created_at: created_at, parent_id: parent_id, parent_path: parent_path, leaf_id: nil, modified_at: created_at)
     end
 
     def create_from_conversation(conversation, parent_session: nil)
@@ -291,16 +321,19 @@ module Kward
       )
       restore_tool_output_artifacts(records, conversation)
       conversation.mark_last_entry_compaction! if latest_record_type(records) == "compaction"
+      created_at = parse_time(header["timestamp"]) || File.mtime(resolved_path)
       session = Session.new(
         store: self,
         id: header["id"],
         path: resolved_path,
         cwd: header["cwd"].to_s,
-        created_at: parse_time(header["timestamp"]) || File.mtime(resolved_path),
+        created_at: created_at,
         name: name,
         parent_id: header["parentId"],
         parent_path: header["parentPath"],
-        leaf_id: leaf_id
+        leaf_id: leaf_id,
+        modified_at: session_modified_at(records, fallback: created_at),
+        system_prompt_hash: latest_system_prompt_hash(records)
       )
       session.attach(conversation)
       [session, conversation]
@@ -315,6 +348,16 @@ module Kward
       recent_sessions(limit: limit, keep_empty_path: keep_empty_path)
     end
 
+    # Lists all persisted sessions under this config directory for an explicit
+    # user-selected operation such as skill capture. Unlike #recent, this is not
+    # scoped to the store's current workspace.
+    def capture_candidates
+      pattern = File.join(@config_dir, "sessions", "**", "*.jsonl")
+      Dir.glob(pattern).filter_map { |path| session_info(path) }.sort_by(&:modified_at).reverse
+    rescue StandardError
+      []
+    end
+
     # Persists the last active session pointer for workspace auto-resume.
     def remember_last_session(session)
       return unless session&.path
@@ -381,21 +424,25 @@ module Kward
     end
 
     def append_leaf_change(path, leaf_id)
-      append_record(path, {
+      record = {
         type: "leaf",
         timestamp: Time.now.utc.iso8601(3),
         targetId: leaf_id
-      })
+      }
+      append_record(path, record)
+      record
     end
 
     def append_label_change(path, entry_id, label)
-      append_record(path, {
+      record = {
         type: "label",
         id: next_entry_id(path),
         timestamp: Time.now.utc.iso8601(3),
         targetId: entry_id.to_s,
         label: label.to_s.strip.empty? ? nil : label.to_s.strip
-      })
+      }
+      append_record(path, record)
+      record
     end
 
     # @return [Array<Hash>] nested session tree roots for the given session file
@@ -430,6 +477,22 @@ module Kward
       current_leaf_id(records_from_file(resolve_session_path(path)))
     end
 
+    # Returns the complete persisted active branch for an explicit export-like
+    # consumer. Unlike #load, this does not attach a conversation or mutate the
+    # session file.
+    #
+    # @return [Hash] session metadata, saved system-prompt snapshots, and active branch records
+    def capture_branch(path)
+      resolved_path = resolve_session_path(path)
+      records = records_from_file(resolved_path)
+      {
+        path: resolved_path,
+        header: session_header(records, resolved_path),
+        system_prompts: records.select { |record| record["type"] == "system_prompt" },
+        entries: branch_records(records)
+      }
+    end
+
     def append_record(path, record)
       File.open(path, "a", 0o600) do |file|
         file.write(JSON.generate(record))
@@ -437,18 +500,22 @@ module Kward
       end
     end
 
-    def append_system_prompt_snapshot(path, system_message, reason: "changed")
+    def append_system_prompt_snapshot(path, system_message, reason: "changed", latest_hash: nil)
       content = MessageAccess.content(system_message).to_s
-      return if content.empty?
-      return if latest_system_prompt_hash(records_from_file(path)) == system_prompt_hash(content)
+      return latest_hash if content.empty?
+
+      hash = system_prompt_hash(content)
+      latest_hash ||= latest_system_prompt_hash(records_from_file(path))
+      return latest_hash if latest_hash == hash
 
       append_record(path, {
         type: "system_prompt",
         timestamp: Time.now.utc.iso8601(3),
         reason: reason.to_s,
-        hash: system_prompt_hash(content),
+        hash: hash,
         content: content
       })
+      hash
     end
 
     def self.safe_cwd(cwd)
@@ -457,6 +524,16 @@ module Kward
 
     private
 
+    def session_modified_at(records, fallback:)
+      records.reverse_each do |record|
+        next if NON_ACTIVITY_RECORD_TYPES.include?(record["type"].to_s)
+
+        timestamp = parse_time(record["timestamp"])
+        return timestamp if timestamp
+      end
+      fallback
+    end
+
     def latest_system_prompt_hash(records)
       records.reverse_each do |record|
         next unless record["type"] == "system_prompt"
@@ -725,7 +802,7 @@ module Kward
     end
 
     def next_entry_id(_path)
-      SecureRandom.hex(4)
+      SecureRandom.hex(16)
     end
 
     def message_entry_id(message)
@@ -771,7 +848,7 @@ module Kward
       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
+      paths = Dir.glob(File.join(session_dir, "*.jsonl")).sort_by { |path| session_file_activity_time(path) }.reverse
       sessions = []
 
       paths.each do |path|
@@ -798,8 +875,16 @@ module Kward
       false
     end
 
-    def session_file_mtime(path)
-      File.mtime(path)
+    def session_file_activity_time(path)
+      latest_timestamp = nil
+      File.foreach(path) do |line|
+        type = line[RECORD_TYPE_PATTERN, 1]
+        next if NON_ACTIVITY_RECORD_TYPES.include?(type.to_s)
+
+        timestamp = line[RECORD_TIMESTAMP_PATTERN, 1]
+        latest_timestamp = timestamp if timestamp
+      end
+      parse_time(latest_timestamp) || File.mtime(path)
     rescue StandardError
       Time.at(0)
     end
@@ -867,13 +952,14 @@ module Kward
       runtime = session_runtime(records, header)
       first_message = messages.find { |message| ["user", "compactionSummary"].include?(message_role(message)) }
       stats = File.stat(path)
+      created_at = parse_time(header["timestamp"]) || stats.mtime
 
       SessionInfo.new(
         id: header["id"],
         path: path,
         cwd: header["cwd"].to_s,
-        created_at: parse_time(header["timestamp"]) || stats.mtime,
-        modified_at: stats.mtime,
+        created_at: created_at,
+        modified_at: session_modified_at(records, fallback: stats.mtime),
         name: name,
         first_message: first_message ? message_text(first_message) : "",
         message_count: messages.count { |message| ["user", "assistant", "tool", "toolResult", "compactionSummary"].include?(message_role(message)) },