kward 0.67.0 → 0.68.0

data/lib/kward/workspace.rb

@@ -3,7 +3,19 @@ require "pathname"
 require "timeout"
 require_relative "session_diff"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Filesystem and shell-command boundary for workspace tools.
+  #
+  # `Workspace` is deliberately low-level: it validates paths, enforces output
+  # limits, applies exact edits, writes files, and runs shell commands from one
+  # root directory. It should not know about model prompts, sessions, telemetry,
+  # or UI confirmation. Tool wrappers and frontends provide those policies.
+  #
+  # Guardrails are enabled by default and require all file paths to resolve under
+  # `root`. RPC may report when guardrails are disabled, but callers should avoid
+  # bypassing this class for local filesystem mutation so read-before-write and
+  # path safety remain consistent.
   class Workspace
     MAX_FILE_BYTES = 256 * 1024
     MAX_READ_OUTPUT_BYTES = 50 * 1024
@@ -12,6 +24,7 @@ module Kward
     MAX_EDIT_DIFF_BYTES = 8 * 1024
     DEFAULT_COMMAND_TIMEOUT_SECONDS = 30
 
+    # 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)
       @root = Pathname.new(root).realpath
       @guardrails = guardrails
@@ -21,8 +34,10 @@ module Kward
       @max_command_output_bytes = max_command_output_bytes
     end
 
+    # @return [Pathname] canonical workspace root used as the base for file and shell tools
     attr_reader :root
 
+    # Lists immediate directory children after resolving `path` through workspace guardrails.
     def list_directory(path)
       resolved = workspace_path(path)
       return "Error: not a directory: #{path}" unless File.directory?(resolved)
@@ -34,6 +49,11 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Reads a bounded text slice from a workspace file.
+    #
+    # The returned string is user/model-facing and includes continuation notices
+    # when output is truncated. Errors are returned as `"Error: ..."` strings so
+    # tool calls can be persisted in the conversation without raising.
     def read_file(path, offset: nil, limit: nil)
       resolved = workspace_path(path)
       return "Error: not a file: #{path}" unless File.file?(resolved)
@@ -41,11 +61,20 @@ module Kward
       size = File.size(resolved)
       return "Error: file too large: #{path} is #{size} bytes; limit is #{@max_file_bytes} bytes" if size > @max_file_bytes
 
-      read_file_slice(File.read(resolved), offset: offset, limit: limit)
+      content = File.read(resolved)
+      return "Error: not a text file: #{path}" if binary_content?(content)
+
+      read_file_slice(content, offset: offset, limit: limit)
     rescue SecurityError, Errno::ENOENT => e
       "Error: #{e.message}"
     end
 
+    # Writes complete file content after enforcing read-before-write for
+    # existing files.
+    #
+    # `read_paths` must contain resolved paths previously observed by
+    # `ReadFile`; this keeps tool-driven edits explicit and prevents overwriting
+    # unseen user files.
     def write_file(path, content, read_paths:)
       resolved = workspace_write_path(path)
 
@@ -53,10 +82,6 @@ module Kward
         return "Error: existing file must be read before writing: #{path}"
       end
 
-      if block_given? && !yield(relative_path(resolved), content.bytesize)
-        return "Declined: write_file was not approved for #{path}"
-      end
-
       old_content = File.exist?(resolved) ? File.read(resolved) : nil
       File.write(resolved, content)
       output = "Wrote #{content.bytesize} bytes to #{path}"
@@ -66,6 +91,11 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Applies exact non-overlapping replacements to a previously read file.
+    #
+    # Each `old_text` must match exactly once. This favors predictable model edits
+    # over fuzzy patching and returns readable error strings when more context is
+    # needed.
     def edit_file(path, edits, read_paths:)
       resolved = workspace_path(path)
       return "Error: not a file: #{path}" unless File.file?(resolved)
@@ -84,6 +114,11 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Runs a shell command from the workspace root with timeout, cancellation,
+    # and bounded combined output.
+    #
+    # This method intentionally does not ask for confirmation; CLI/RPC policy
+    # must decide whether a command is allowed before reaching this boundary.
     def run_shell_command(command, timeout_seconds: DEFAULT_COMMAND_TIMEOUT_SECONDS, cancellation: nil)
       command = command.to_s.strip
       return "Error: command is required" if command.empty?
@@ -114,6 +149,7 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Resolves a path with the same guardrails used by file tools.
     def resolved_path(path)
       workspace_path(path)
     end
@@ -189,6 +225,10 @@ module Kward
       output
     end
 
+    def binary_content?(content)
+      content.include?("\x00")
+    end
+
     def read_start_index(offset)
       return 0 if offset.nil?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kward
 version: !ruby/object:Gem::Version
-  version: 0.67.0
+  version: 0.68.0
 platform: ruby
 authors:
 - Kai Wood
@@ -140,12 +140,28 @@ files:
 - lib/kward.rb
 - lib/kward/agent.rb
 - lib/kward/ansi.rb
+- lib/kward/auth/anthropic_oauth.rb
 - lib/kward/auth/file.rb
 - lib/kward/auth/github_oauth.rb
 - lib/kward/auth/openai_oauth.rb
 - lib/kward/auth/openrouter_api_key.rb
 - lib/kward/cancellation.rb
 - lib/kward/cli.rb
+- lib/kward/cli/auth_commands.rb
+- lib/kward/cli/commands.rb
+- lib/kward/cli/compaction.rb
+- lib/kward/cli/doctor.rb
+- lib/kward/cli/interactive_turn.rb
+- lib/kward/cli/memory_commands.rb
+- lib/kward/cli/plugins.rb
+- lib/kward/cli/prompt_interface.rb
+- lib/kward/cli/rendering.rb
+- lib/kward/cli/runtime_helpers.rb
+- lib/kward/cli/sessions.rb
+- lib/kward/cli/settings.rb
+- lib/kward/cli/slash_commands.rb
+- lib/kward/cli/stats.rb
+- lib/kward/cli/tool_summaries.rb
 - lib/kward/cli_transcript_formatter.rb
 - lib/kward/clipboard.rb
 - lib/kward/compaction/file_operation_tracker.rb
@@ -158,6 +174,7 @@ files:
 - lib/kward/markdown_transcript.rb
 - lib/kward/memory/manager.rb
 - lib/kward/message_access.rb
+- lib/kward/message_text.rb
 - lib/kward/model/chat_invocation.rb
 - lib/kward/model/client.rb
 - lib/kward/model/context_overflow.rb
@@ -172,11 +189,28 @@ files:
 - lib/kward/private_file.rb
 - lib/kward/prompt_interface.rb
 - lib/kward/prompt_interface/banner.rb
+- lib/kward/prompt_interface/composer_controller.rb
+- lib/kward/prompt_interface/composer_renderer.rb
+- lib/kward/prompt_interface/composer_state.rb
+- lib/kward/prompt_interface/key_handler.rb
+- lib/kward/prompt_interface/layout.rb
+- lib/kward/prompt_interface/overlay_renderer.rb
+- lib/kward/prompt_interface/prompt_renderer.rb
+- lib/kward/prompt_interface/question_prompt.rb
+- lib/kward/prompt_interface/runtime_state.rb
+- lib/kward/prompt_interface/screen.rb
+- lib/kward/prompt_interface/selection_prompt.rb
+- lib/kward/prompt_interface/slash_overlay.rb
+- lib/kward/prompt_interface/stream_state.rb
+- lib/kward/prompt_interface/transcript_buffer.rb
+- lib/kward/prompt_interface/transcript_renderer.rb
 - lib/kward/prompts.rb
 - lib/kward/prompts/commands.rb
 - lib/kward/prompts/templates.rb
+- lib/kward/question_contract.rb
 - lib/kward/resources/avatar_kward_logo.rb
 - lib/kward/resources/pixel_logo.rb
+- lib/kward/rpc/attachment_normalizer.rb
 - lib/kward/rpc/auth_manager.rb
 - lib/kward/rpc/config_manager.rb
 - lib/kward/rpc/prompt_bridge.rb
@@ -184,6 +218,9 @@ files:
 - lib/kward/rpc/runtime_payloads.rb
 - lib/kward/rpc/server.rb
 - lib/kward/rpc/session_manager.rb
+- lib/kward/rpc/session_metrics.rb
+- lib/kward/rpc/session_tree.rb
+- lib/kward/rpc/session_tree_rows.rb
 - lib/kward/rpc/tool_event_normalizer.rb
 - lib/kward/rpc/tool_metadata.rb
 - lib/kward/rpc/transcript_normalizer.rb
@@ -192,6 +229,7 @@ files:
 - lib/kward/session_store.rb
 - lib/kward/session_trash.rb
 - lib/kward/session_tree_renderer.rb
+- lib/kward/session_tree_tool_display.rb
 - lib/kward/skills/registry.rb
 - lib/kward/starter_pack_installer.rb
 - lib/kward/steering.rb
@@ -220,6 +258,10 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/kaiwood/kward
+  changelog_uri: https://github.com/kaiwood/kward/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/kaiwood/kward#readme
+  bug_tracker_uri: https://github.com/kaiwood/kward/issues
 rdoc_options: []
 require_paths:
 - lib