kward 0.78.0 → 0.79.0

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/tools/registry.rb

@@ -49,6 +49,19 @@ module Kward
   # explicit tool errors.
   # @api public
   class ToolRegistry
+    CORE_TOOL_NAMES = %w[
+      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
+    ].freeze
+
     # Tool schemas advertised to the model for the current frontend and config.
     #
     # @return [Array<Hash>] tool schemas currently advertised to the model
@@ -462,13 +475,15 @@ module Kward
     def build_tools
       tools = all_tools
       tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names
-      tools.to_h { |tool| [tool.name, tool] }
+      tools.each_with_object({}) do |tool, result|
+        raise ArgumentError, "Duplicate tool name: #{tool.name}" if result.key?(tool.name)
+
+        result[tool.name] = tool
+      end
     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", "context_for_task", "context_budget_stats", "retrieve_tool_output"
-      )
+      tools = @tools.values_at(*CORE_TOOL_NAMES)
       tools.concat(@tools.values_at("web_search", "fetch_content", "fetch_raw")) if web_search_available?
       tools.concat(@tools.values.select { |tool| tool.is_a?(Tools::MCPTool) })
       tools << @tools["read_skill"] if skills_available?

data/lib/kward/version.rb

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

data/lib/kward/workspace.rb

@@ -1,5 +1,6 @@
 require "pathname"
 require_relative "local_command_runner"
+require_relative "sandbox"
 require_relative "session_diff"
 
 require_relative "path_guard"
@@ -27,13 +28,14 @@ module Kward
     EXPECTED_FILE_ERRORS = [SecurityError, Errno::ENOENT, Errno::EACCES, Errno::EPERM, Errno::EISDIR, Errno::ENOTDIR].freeze
 
     # Creates an object for workspace filesystem and shell operations.
-    def initialize(root: Dir.pwd, max_file_bytes: MAX_FILE_BYTES, max_read_output_bytes: MAX_READ_OUTPUT_BYTES, max_read_output_lines: MAX_READ_OUTPUT_LINES, max_command_output_bytes: MAX_COMMAND_OUTPUT_BYTES, guardrails: true)
+    def initialize(root: Dir.pwd, max_file_bytes: MAX_FILE_BYTES, max_read_output_bytes: MAX_READ_OUTPUT_BYTES, max_read_output_lines: MAX_READ_OUTPUT_LINES, max_command_output_bytes: MAX_COMMAND_OUTPUT_BYTES, guardrails: true, command_runner: nil)
       @root = Pathname.new(root).realpath
       @guardrails = guardrails
       @max_file_bytes = max_file_bytes
       @max_read_output_bytes = max_read_output_bytes
       @max_read_output_lines = max_read_output_lines
       @max_command_output_bytes = max_command_output_bytes
+      @command_runner = command_runner
     end
 
     # @return [Pathname] canonical workspace root used as the base for file and shell tools
@@ -162,7 +164,13 @@ module Kward
       timeout_seconds = DEFAULT_COMMAND_TIMEOUT_SECONDS if timeout_seconds <= 0
       cancellation&.raise_if_cancelled!
 
-      result = LocalCommandRunner.new(timeout_seconds: timeout_seconds, max_output_bytes: @max_command_output_bytes).run(command, cwd: @root.to_s, cancellation: cancellation)
+      result = command_runner.run(
+        command,
+        cwd: @root.to_s,
+        timeout_seconds: timeout_seconds,
+        max_output_bytes: @max_command_output_bytes,
+        cancellation: cancellation
+      )
       return "Error: command timed out after #{timeout_seconds} seconds" if result.timed_out
 
       output = +"Exit status: #{result.exit_status}\n"
@@ -170,7 +178,7 @@ module Kward
       output << "\nSTDERR:\n#{result.stderr}" unless result.stderr.empty?
       output << "\n... truncated to #{@max_command_output_bytes} bytes" if result.truncated
       truncate_output(output)
-    rescue Errno::ENOENT, ArgumentError => e
+    rescue Errno::ENOENT, ArgumentError, Sandbox::UnavailableError => e
       "Error: #{e.message}"
     end
 
@@ -181,6 +189,13 @@ module Kward
 
     private
 
+    def command_runner
+      @command_runner ||= Sandbox::PassthroughRunner.new(
+        policy: Sandbox::Policy.new(workspace_root: @root),
+        capabilities: Sandbox::RunnerFactory.off_capabilities
+      )
+    end
+
     def workspace_path(path)
       target = Pathname.new(path.to_s)
       target = @root.join(target) unless target.absolute?

data/lib/kward/workspace_factory.rb

@@ -0,0 +1,17 @@
+require_relative "config_files"
+require_relative "sandbox"
+require_relative "workspace"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Builds workspaces with the same user-configured command sandbox in every frontend.
+  module WorkspaceFactory
+    module_function
+
+    def build(root:, guardrails: true, config: ConfigFiles.read_config)
+      policy = ConfigFiles.sandbox_policy(root, config)
+      runner = Sandbox::RunnerFactory.build(policy)
+      Workspace.new(root:, guardrails:, command_runner: runner)
+    end
+  end
+end

data/templates/default/fulldoc/html/js/kward.js

@@ -4,6 +4,7 @@ const guideLinks = {
   'doc/usage.md': 'file.usage.html',
   'doc/configuration.md': 'file.configuration.html',
   'doc/authentication.md': 'file.authentication.html',
+  'doc/sandboxing.md': 'file.sandboxing.html',
   'doc/troubleshooting.md': 'file.troubleshooting.html',
   'doc/session-management.md': 'file.session-management.html',
   'doc/memory.md': 'file.memory.html',

data/templates/default/kward_navigation.rb

@@ -22,7 +22,8 @@ module KwardDocsNavigationData
         ["Memory", "file.memory.html"],
         ["Personas", "file.personas.html"],
         ["Skills", "file.skills.html"],
-        ["Pan mode", "file.pan.html"]
+        ["Pan mode", "file.pan.html"],
+        ["Local models", "file.local-models.html"]
       ]
     ],
     [
@@ -43,7 +44,8 @@ module KwardDocsNavigationData
         ["Extensibility", "file.extensibility.html"],
         ["Plugins", "file.plugins.html"],
         ["Lifecycle hooks", "file.lifecycle-hooks.html"],
-        ["Permissions", "file.permissions.html"]
+        ["Permissions", "file.permissions.html"],
+        ["Command sandboxing", "file.sandboxing.html"]
       ]
     ],
     [

data/templates/default/layout/html/setup.rb

@@ -30,6 +30,7 @@ module KwardDocsNavigation
     "doc/configuration.md" => "file.configuration.html",
     "doc/authentication.md" => "file.authentication.html",
     "doc/permissions.md" => "file.permissions.html",
+    "doc/sandboxing.md" => "file.sandboxing.html",
     "doc/troubleshooting.md" => "file.troubleshooting.html",
     "doc/session-management.md" => "file.session-management.html",
     "doc/tabs.md" => "file.tabs.html",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kward
 version: !ruby/object:Gem::Version
-  version: 0.78.0
+  version: 0.79.0
 platform: ruby
 authors:
 - Kai Wood
@@ -139,6 +139,7 @@ files:
 - doc/getting-started.md
 - doc/git.md
 - doc/lifecycle-hooks.md
+- doc/local-models.md
 - doc/mcp.md
 - doc/memory.md
 - doc/pan.md
@@ -147,6 +148,7 @@ files:
 - doc/plugins.md
 - doc/releasing.md
 - doc/rpc.md
+- doc/sandboxing.md
 - doc/security.md
 - doc/session-management.md
 - doc/shell.md
@@ -314,6 +316,16 @@ files:
 - lib/kward/rpc/transcript_normalizer.rb
 - lib/kward/rpc/transport.rb
 - lib/kward/rpc/turn_context.rb
+- lib/kward/sandbox.rb
+- lib/kward/sandbox/capabilities.rb
+- lib/kward/sandbox/command_runner.rb
+- lib/kward/sandbox/environment.rb
+- lib/kward/sandbox/linux_bubblewrap_runner.rb
+- lib/kward/sandbox/macos_seatbelt_runner.rb
+- lib/kward/sandbox/passthrough_runner.rb
+- lib/kward/sandbox/policy.rb
+- lib/kward/sandbox/runner_factory.rb
+- lib/kward/sandbox/unavailable_runner.rb
 - lib/kward/scratchpad_runner.rb
 - lib/kward/session_diff.rb
 - lib/kward/session_naming.rb
@@ -322,6 +334,7 @@ files:
 - lib/kward/session_tree_nodes.rb
 - lib/kward/session_tree_renderer.rb
 - lib/kward/session_tree_tool_display.rb
+- lib/kward/skills/capture.rb
 - lib/kward/skills/registry.rb
 - lib/kward/starter_pack_installer.rb
 - lib/kward/steering.rb
@@ -359,6 +372,7 @@ files:
 - lib/kward/update_check.rb
 - lib/kward/version.rb
 - lib/kward/workspace.rb
+- lib/kward/workspace_factory.rb
 - lib/main.rb
 - templates/default/fulldoc/html/css/kward.css
 - templates/default/fulldoc/html/full_list.erb
@@ -386,7 +400,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="