kward 0.77.0 → 0.79.0

data/lib/kward/sandbox/command_runner.rb

@@ -0,0 +1,28 @@
+require_relative "../local_command_runner"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Base command runner. Platform runners provide an argv that is then executed
+    # through LocalCommandRunner, preserving Kward's timeout and cancellation behavior.
+    class CommandRunner
+      def initialize(policy:, capabilities:)
+        @policy = policy
+        @capabilities = capabilities
+      end
+
+      attr_reader :policy, :capabilities
+
+      def run(command, cwd:, timeout_seconds:, max_output_bytes:, cancellation: nil, &block)
+        LocalCommandRunner.new(
+          timeout_seconds: timeout_seconds,
+          max_output_bytes: max_output_bytes
+        ).run(*command_argv(command, cwd: cwd), cwd: cwd, cancellation: cancellation, &block)
+      end
+
+      def command_argv(command, cwd:)
+        raise NotImplementedError, "#{self.class} must implement #command_argv"
+      end
+    end
+  end
+end

data/lib/kward/sandbox/environment.rb

@@ -0,0 +1,24 @@
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Builds a minimal environment for sandboxed command workers. In particular,
+    # credentials and language-runtime injection variables are not inherited.
+    module Environment
+      SAFE_VARIABLES = %w[PATH LANG LC_ALL LC_CTYPE TERM COLORTERM NO_COLOR].freeze
+
+      module_function
+
+      def command_worker(temporary_root, source: ENV)
+        SAFE_VARIABLES.each_with_object({}) do |name, environment|
+          value = source[name].to_s
+          environment[name] = value unless value.empty?
+        end.merge(
+          "HOME" => temporary_root,
+          "TMPDIR" => temporary_root,
+          "TMP" => temporary_root,
+          "TEMP" => temporary_root
+        )
+      end
+    end
+  end
+end

data/lib/kward/sandbox/linux_bubblewrap_runner.rb

@@ -0,0 +1,71 @@
+require "fileutils"
+require "tmpdir"
+require_relative "command_runner"
+require_relative "environment"
+
+# Namespace for operating-system command sandboxing.
+module Kward
+  module Sandbox
+    # Runs a command in a Bubblewrap mount namespace on Linux.
+    class LinuxBubblewrapRunner < CommandRunner
+      def self.executable
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).filter_map do |directory|
+          path = File.expand_path("bwrap", directory)
+          path if File.file?(path) && File.executable?(path)
+        end.first
+      end
+
+      def self.capabilities(platform: RUBY_PLATFORM, executable: self.executable)
+        available = platform.to_s.include?("linux") && !executable.to_s.empty?
+        return Capabilities.new(available: true, filesystem_enforced: true, child_network_enforced: true, backend: "linux_bubblewrap") if available
+
+        Capabilities.new(
+          available: false,
+          filesystem_enforced: false,
+          child_network_enforced: false,
+          backend: "linux_bubblewrap",
+          reason: "Bubblewrap is unavailable"
+        )
+      end
+
+      def initialize(policy:, executable: self.class.executable, capabilities: self.class.capabilities(executable: executable))
+        raise ArgumentError, "Linux Bubblewrap is unavailable: #{capabilities.reason}" unless capabilities.available?
+
+        super(policy:, capabilities:)
+        @executable = executable
+      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
+        workspace_root = policy.workspace_root
+        writable_roots = policy.command_writable_roots + [File.realpath(temporary_root)]
+        argv = [@executable, "--die-with-parent", "--new-session", "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc"]
+        argv << "--unshare-net" unless policy.child_network_allowed?
+        argv.concat(["--bind", workspace_root, workspace_root]) if policy.workspace_write?
+        writable_roots.reject { |path| path == workspace_root }.each { |path| argv.concat(["--bind", path, path]) }
+        argv.concat(["--ro-bind", File.join(workspace_root, ".git"), File.join(workspace_root, ".git")]) if policy.protect_git_metadata? && File.exist?(File.join(workspace_root, ".git"))
+        argv.concat(["--setenv", "TMPDIR", temporary_root, "--setenv", "TMP", temporary_root, "--setenv", "TEMP", temporary_root])
+        argv.concat(["--chdir", cwd.to_s, "--", "/bin/sh", "-lc", command.to_s])
+      end
+    end
+  end
+end

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

@@ -315,6 +315,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
@@ -430,6 +440,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))

data/lib/kward/skills/capture.rb

@@ -0,0 +1,144 @@
+require "fileutils"
+require "json"
+require "tempfile"
+require "yaml"
+require_relative "../compaction/token_estimator"
+require_relative "../config_files"
+require_relative "../message_access"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Skills
+    # Generates and persists reviewed personal skills from saved session branches.
+    class Capture
+      Draft = Struct.new(:content, :source_path, :name, :description, keyword_init: true)
+
+      class Error < StandardError; end
+      class SourceTooLargeError < Error; end
+      class InvalidDraftError < Error; end
+      class ConflictError < Error; end
+
+      OUTPUT_TOKEN_RESERVE = 4_096
+      PROMPT_TOKEN_RESERVE = 1_024
+      NAME_PATTERN = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+      def initialize(session_store:, client:, config_dir: ConfigFiles.config_dir, token_estimator: Compaction::TokenEstimator.new)
+        @session_store = session_store
+        @client = client
+        @config_dir = config_dir
+        @token_estimator = token_estimator
+      end
+
+      def generate(session_path, cancellation: nil)
+        ensure_personal_session_path!(session_path)
+        source = @session_store.capture_branch(session_path)
+        raise Error, "Session has no active branch to capture" if source[:entries].empty?
+
+        source_json = JSON.pretty_generate(source)
+        ensure_source_fits!(source_json)
+        response = @client.chat(draft_messages(source_json), tools: [], cancellation: cancellation)
+        draft(source_path: source[:path], content: MessageAccess.content(response).to_s)
+      end
+
+      def save(content, overwrite: false)
+        reviewed_draft = draft(content: content)
+        path = skill_path(reviewed_draft.name)
+        if File.exist?(path) && !overwrite
+          raise ConflictError, "A personal skill named #{reviewed_draft.name.inspect} already exists"
+        end
+
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        write_atomically(path, reviewed_draft.content)
+        reviewed_draft
+      end
+
+      def skill_path(name)
+        File.join(@config_dir, "skills", name.to_s, "SKILL.md")
+      end
+
+      private
+
+      def ensure_personal_session_path!(session_path)
+        sessions_root = File.realpath(File.join(@config_dir, "sessions"))
+        source_path = File.realpath(session_path)
+        return if source_path.start_with?("#{sessions_root}#{File::SEPARATOR}")
+
+        raise Error, "Skill capture source must be a persisted Kward session"
+      rescue Errno::ENOENT
+        raise Error, "Skill capture source must be a persisted Kward session"
+      end
+
+      def ensure_source_fits!(source_json)
+        context_window = @client.current_context_window
+        return unless context_window
+
+        available_tokens = context_window.to_i - OUTPUT_TOKEN_RESERVE - PROMPT_TOKEN_RESERVE
+        source_tokens = @token_estimator.estimate_tokens(source_json)
+        return if source_tokens <= available_tokens
+
+        raise SourceTooLargeError,
+          "Selected session needs about #{source_tokens} tokens, but only #{[available_tokens, 0].max} are available for capture"
+      end
+
+      def draft_messages(source_json)
+        [
+          {
+            role: "system",
+            content: <<~INSTRUCTIONS
+              Create one reusable Kward Agent Skill from the saved session supplied by the user.
+              Return only a complete SKILL.md document. Include YAML frontmatter with a lowercase
+              hyphenated `name` and a concise `description`, followed by practical reusable
+              instructions. Derive guidance from demonstrated workflow, commands, and conventions;
+              omit credentials, private values, and project-specific incidental details. Do not
+              claim the skill grants permissions or tool access.
+            INSTRUCTIONS
+          },
+          {
+            role: "user",
+            content: "Saved session active branch (complete persisted records):\n\n#{source_json}"
+          }
+        ]
+      end
+
+      def draft(source_path: nil, content:)
+        metadata, body = parse_skill(content)
+        name = metadata.fetch("name", "").to_s.strip
+        description = metadata.fetch("description", "").to_s.strip
+        raise InvalidDraftError, "Skill frontmatter must include a name" if name.empty?
+        raise InvalidDraftError, "Skill name must use lowercase letters, digits, and hyphens" unless NAME_PATTERN.match?(name)
+        raise InvalidDraftError, "Skill frontmatter must include a description" if description.empty?
+        raise InvalidDraftError, "Skill description exceeds 1024 characters" if description.length > 1024
+        raise InvalidDraftError, "Skill instructions must not be empty" if body.strip.empty?
+
+        Draft.new(content: normalize_content(content), source_path: source_path, name: name, description: description)
+      end
+
+      def parse_skill(content)
+        match = content.to_s.match(/\A---\r?\n(.*?)\r?\n---\r?\n(.*)\z/m)
+        raise InvalidDraftError, "Skill must begin with YAML frontmatter" unless match
+
+        metadata = YAML.safe_load(match[1], permitted_classes: [], aliases: false)
+        raise InvalidDraftError, "Skill frontmatter must be a mapping" unless metadata.is_a?(Hash)
+
+        [metadata.transform_keys(&:to_s), match[2]]
+      rescue Psych::SyntaxError => error
+        raise InvalidDraftError, "Invalid skill frontmatter: #{error.message}"
+      end
+
+      def normalize_content(content)
+        "#{content.to_s.rstrip}\n"
+      end
+
+      def write_atomically(path, content)
+        Tempfile.create(["SKILL", ".tmp"], File.dirname(path)) do |file|
+          file.write(content)
+          file.flush
+          file.fsync
+          File.chmod(0o600, file.path)
+          File.rename(file.path, path)
+        end
+        File.chmod(0o600, path)
+      end
+    end
+  end
+end

data/lib/kward/starter_pack_installer.rb

@@ -6,6 +6,7 @@ require "tmpdir"
 require "uri"
 require "zlib"
 require_relative "config_files"
+require_relative "http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -56,8 +57,9 @@ module Kward
 
     def download(url)
       uri = URI(url)
+      request = Http.apply_user_agent(Net::HTTP::Get.new(uri))
       response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
-        http.get(uri.request_uri)
+        http.request(request)
       end
       raise "Starter pack download failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)