kward 0.73.1 → 0.75.0

data/lib/kward/hooks/audit_log.rb

@@ -0,0 +1,121 @@
+require "fileutils"
+require "json"
+require "time"
+require_relative "../config_files"
+require_relative "../rpc/redactor"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Append-only JSONL audit log for lifecycle hook activity.
+    class AuditLog
+      DEFAULT_MAX_BYTES = 10 * 1024 * 1024
+
+      def initialize(path: nil, config_path: ConfigFiles.config_path, max_bytes: DEFAULT_MAX_BYTES, clock: Time, monotonic_clock: Process, error_output: $stderr)
+        @path = path
+        @config_path = config_path
+        @max_bytes = max_bytes.to_i.positive? ? max_bytes.to_i : DEFAULT_MAX_BYTES
+        @clock = clock
+        @monotonic_clock = monotonic_clock
+        @error_output = error_output
+        @mutex = Mutex.new
+        @warned = false
+      end
+
+      def monotonic_now
+        @monotonic_clock.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def duration_ms(started_at)
+        ((monotonic_now - started_at.to_f) * 1000).round(1)
+      end
+
+      def log_handler(event:, handler:, decision:, duration_ms: nil)
+        write_record(
+          "kind" => "handler",
+          "event_id" => event.id,
+          "event" => event.name,
+          "phase" => event.phase,
+          "hook_id" => handler.id,
+          "source" => handler.source,
+          "decision" => decision.decision,
+          "message" => redact_string(decision.message),
+          "duration_ms" => duration_ms,
+          "payload_keys" => safe_keys(event.payload),
+          "modified_keys" => decision.modify? ? safe_keys(decision.payload) : []
+        )
+      end
+
+      def log_result(event:, result:)
+        write_record(
+          "kind" => "result",
+          "event_id" => event.id,
+          "event" => event.name,
+          "phase" => event.phase,
+          "decision" => result.decision.decision,
+          "message" => redact_string(result.decision.message),
+          "handler_count" => result.decisions.length,
+          "warnings" => result.warnings.map { |warning| redact_string(warning) },
+          "messages" => result.messages.map { |message| redact_string(message) },
+          "payload_keys" => safe_keys(result.payload)
+        )
+      end
+
+      private
+
+      def write_record(payload)
+        @mutex.synchronize do
+          path = current_path
+          FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+          File.open(path, File::WRONLY | File::CREAT | File::APPEND, 0o600) do |file|
+            file.write(JSON.generate(payload.compact.merge("timestamp" => @clock.now.utc.iso8601(3))))
+            file.write("\n")
+          end
+          File.chmod(0o600, path)
+        end
+        true
+      rescue StandardError => e
+        warn_once(e)
+        false
+      end
+
+      def current_path
+        explicit_path = @path || File.join(File.dirname(File.expand_path(@config_path)), "logs", "hooks.jsonl")
+        return explicit_path if writable_log_path?(explicit_path)
+
+        index = 1
+        loop do
+          path = explicit_path.sub(/\.jsonl\z/, "-#{index}.jsonl")
+          return path if writable_log_path?(path)
+
+          index += 1
+        end
+      end
+
+      def writable_log_path?(path)
+        !File.exist?(path) || File.size(path) < @max_bytes
+      end
+
+      def safe_keys(value)
+        return [] unless value.is_a?(Hash)
+
+        value.keys.map(&:to_s).sort
+      end
+
+      def redact_string(value)
+        return nil if value.nil?
+
+        RPC::Redactor.redact_string(value.to_s)[0, 500]
+      end
+
+      def warn_once(error)
+        return if @warned
+
+        @warned = true
+        @error_output&.puts("Warning: hook audit logging failed: #{error.message}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/kward/hooks/catalog.rb

@@ -0,0 +1,110 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Known lifecycle hook events and their safety defaults.
+    module Catalog
+      DEFAULT_FAILURE_POLICY = "warn"
+      VALID_FAILURE_POLICIES = %w[allow warn deny ask].freeze
+
+      EventDefinition = Struct.new(:name, :failure_policy, :modifiable_fields, keyword_init: true)
+
+      DEFINITIONS = [
+        EventDefinition.new(name: "turn_start", failure_policy: "warn", modifiable_fields: %w[input display_input]),
+        EventDefinition.new(name: "turn_context_build_before", failure_policy: "warn"),
+        EventDefinition.new(name: "turn_context_build_after", failure_policy: "warn"),
+        EventDefinition.new(name: "model_request_before", failure_policy: "warn", modifiable_fields: %w[messages tools provider model reasoning]),
+        EventDefinition.new(name: "turn_model_request_before", failure_policy: "warn"),
+        EventDefinition.new(name: "model_response_after_parse", failure_policy: "warn"),
+        EventDefinition.new(name: "turn_model_response_complete", failure_policy: "warn"),
+        EventDefinition.new(name: "turn_end", failure_policy: "warn"),
+        EventDefinition.new(name: "session_create", failure_policy: "warn"),
+        EventDefinition.new(name: "session_resume", failure_policy: "warn"),
+        EventDefinition.new(name: "session_clone", failure_policy: "warn"),
+        EventDefinition.new(name: "session_fork", failure_policy: "warn"),
+        EventDefinition.new(name: "session_rename", failure_policy: "warn"),
+        EventDefinition.new(name: "session_export_before", failure_policy: "deny"),
+        EventDefinition.new(name: "session_export_after", failure_policy: "warn"),
+        EventDefinition.new(name: "session_compact_before", failure_policy: "deny"),
+        EventDefinition.new(name: "session_compact_after", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_output_compact_before", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_output_compact_after", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_call_before", failure_policy: "deny", modifiable_fields: %w[arguments]),
+        EventDefinition.new(name: "tool_call_after", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_call_error", failure_policy: "warn"),
+        EventDefinition.new(name: "mcp_tool_before", failure_policy: "deny"),
+        EventDefinition.new(name: "mcp_tool_after", failure_policy: "warn"),
+        EventDefinition.new(name: "mcp_tool_error", failure_policy: "warn"),
+        EventDefinition.new(name: "shell_command_before", failure_policy: "deny", modifiable_fields: %w[command timeout_seconds]),
+        EventDefinition.new(name: "shell_command_after", failure_policy: "warn"),
+        EventDefinition.new(name: "file_change_before", failure_policy: "deny"),
+        EventDefinition.new(name: "file_change_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_status_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_diff_before", failure_policy: "deny"),
+        EventDefinition.new(name: "git_diff_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_stage_before", failure_policy: "deny"),
+        EventDefinition.new(name: "git_stage_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_commit_before", failure_policy: "deny"),
+        EventDefinition.new(name: "git_commit_after", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_create", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_start_before", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_start_after", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_ready_for_review", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_failed", failure_policy: "warn")
+      ].each_with_object({}) { |definition, result| result[definition.name] = definition }.freeze
+
+      module_function
+
+      def event_names
+        DEFINITIONS.keys.sort
+      end
+
+      def definition(event_name)
+        DEFINITIONS[event_name.to_s]
+      end
+
+      def known?(event_name)
+        DEFINITIONS.key?(event_name.to_s)
+      end
+
+      def failure_policy(event_name, explicit_policy = nil)
+        normalize_failure_policy(explicit_policy || definition(event_name)&.failure_policy || DEFAULT_FAILURE_POLICY)
+      end
+
+      def normalize_failure_policy(policy)
+        value = policy.to_s
+        return value if VALID_FAILURE_POLICIES.include?(value)
+
+        raise ArgumentError, "Unknown hook failure policy: #{policy}"
+      end
+
+      def modifiable_fields(event_name)
+        Array(definition(event_name)&.modifiable_fields)
+      end
+
+      def filter_modifications(event_name, payload)
+        definition = definition(event_name)
+        return payload unless definition
+
+        fields = Array(definition.modifiable_fields)
+        return {} if fields.empty?
+
+        payload.each_with_object({}) do |(key, value), result|
+          result[key] = value if fields.include?(key.to_s)
+        end
+      end
+
+      def failure_decision(policy, message, metadata: nil)
+        case normalize_failure_policy(policy)
+        when "allow"
+          Decision.allow(message, metadata: metadata)
+        when "warn"
+          Decision.warn(message, metadata: metadata)
+        when "deny"
+          Decision.deny(message, metadata: metadata)
+        when "ask"
+          Decision.ask(message, metadata: metadata)
+        end
+      end
+    end
+  end
+end

data/lib/kward/hooks/command_handler.rb

@@ -0,0 +1,66 @@
+require "json"
+require "open3"
+require "shellwords"
+require "timeout"
+require_relative "catalog"
+require_relative "decision"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Executes an external command hook using JSON over stdin/stdout.
+    class CommandHandler
+      DEFAULT_TIMEOUT_SECONDS = 10
+
+      def initialize(command:, timeout_seconds: DEFAULT_TIMEOUT_SECONDS, env: nil, failure_policy: Catalog::DEFAULT_FAILURE_POLICY)
+        @command = command.to_s
+        @timeout_seconds = positive_timeout(timeout_seconds)
+        @env = stringify_hash(env || {})
+        @failure_policy = Catalog.normalize_failure_policy(failure_policy)
+      end
+
+      def call(event, _context = nil)
+        stdout, stderr, status = run_command(JSON.dump(event.to_h))
+        return failure_decision("Command hook failed: #{stderr.strip.empty? ? "exit #{status.exitstatus}" : stderr.strip}") unless status.success?
+
+        parse_decision(stdout)
+      rescue Timeout::Error
+        failure_decision("Command hook timed out after #{@timeout_seconds}s")
+      rescue StandardError => e
+        failure_decision("Command hook failed: #{e.message}")
+      end
+
+      private
+
+      def run_command(input)
+        Timeout.timeout(@timeout_seconds) do
+          Open3.capture3(@env, *@command.shellsplit, stdin_data: input)
+        end
+      end
+
+      def parse_decision(stdout)
+        text = stdout.to_s.strip
+        return Decision.allow if text.empty?
+
+        Decision.normalize(JSON.parse(text))
+      rescue JSON::ParserError => e
+        failure_decision("Command hook returned invalid JSON: #{e.message}")
+      end
+
+      def failure_decision(message)
+        Catalog.failure_decision(@failure_policy, message)
+      end
+
+      def positive_timeout(value)
+        seconds = value.to_i
+        seconds.positive? ? seconds : DEFAULT_TIMEOUT_SECONDS
+      end
+
+      def stringify_hash(value)
+        value.each_with_object({}) do |(key, item), result|
+          result[key.to_s] = item.to_s
+        end
+      end
+    end
+  end
+end

data/lib/kward/hooks/config_loader.rb

@@ -0,0 +1,104 @@
+require_relative "catalog"
+require_relative "command_handler"
+require_relative "http_handler"
+require_relative "manager"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Builds hook managers from Kward configuration hashes.
+    class ConfigLoader
+      def initialize(config)
+        @config = config || {}
+      end
+
+      def manager
+        Manager.new.tap do |manager|
+          hooks_config.each do |event, entries|
+            Array(entries).each_with_index do |entry, index|
+              register_entry(manager, event.to_s, entry, index)
+            end
+          end
+        end
+      end
+
+      private
+
+      def hooks_config
+        value = @config["hooks"] || @config[:hooks]
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def register_entry(manager, event, entry, index)
+        entry = normalize_entry(entry)
+        return if truthy?(entry["disabled"])
+
+        handler = handler_for(entry)
+        callback = truthy?(entry["async"]) ? async_callback(handler) : handler
+        manager.register(
+          event,
+          id: entry["id"] || "config:#{event}:#{index + 1}",
+          source: "config",
+          order: entry.fetch("order", 100),
+          match: entry["match"],
+          failure_policy: entry["failure_policy"]
+        ) { |hook_event, context| callback.call(hook_event, context) }
+      end
+
+      def normalize_entry(entry)
+        case entry
+        when String
+          { "type" => "command", "command" => entry }
+        when Hash
+          entry.transform_keys(&:to_s)
+        else
+          raise ArgumentError, "Invalid hook config entry: #{entry.inspect}"
+        end
+      end
+
+      def handler_for(entry)
+        type = (entry["type"] || "command").to_s
+        case type
+        when "command"
+          CommandHandler.new(
+            command: required(entry, "command"),
+            timeout_seconds: entry["timeout_seconds"],
+            env: entry["env"],
+            failure_policy: entry["failure_policy"] || Catalog::DEFAULT_FAILURE_POLICY
+          )
+        when "http"
+          HttpHandler.new(
+            url: required(entry, "url"),
+            timeout_seconds: entry["timeout_seconds"],
+            headers: entry["headers"],
+            failure_policy: entry["failure_policy"] || Catalog::DEFAULT_FAILURE_POLICY
+          )
+        else
+          raise ArgumentError, "Unsupported hook type: #{type}"
+        end
+      end
+
+      def async_callback(handler)
+        lambda do |hook_event, context|
+          Thread.new do
+            handler.call(hook_event, context)
+          rescue StandardError
+            nil
+          end
+          Decision.allow("Async hook scheduled")
+        end
+      end
+
+      def required(entry, key)
+        value = entry[key]
+        raise ArgumentError, "Hook config requires #{key}" if value.to_s.empty?
+
+        value
+      end
+
+      def truthy?(value)
+        value == true || value.to_s == "true"
+      end
+    end
+  end
+end

data/lib/kward/hooks/decision.rb

@@ -0,0 +1,102 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Normalized result returned by lifecycle hooks.
+    class Decision
+      VALID_DECISIONS = %w[allow deny ask modify warn retry defer].freeze
+
+      attr_reader :decision, :message, :payload, :metadata
+
+      def initialize(decision:, message: nil, payload: nil, metadata: nil)
+        @decision = decision.to_s
+        raise ArgumentError, "Unknown hook decision: #{@decision}" unless VALID_DECISIONS.include?(@decision)
+
+        @message = message&.to_s
+        @payload = payload || {}
+        @metadata = metadata || {}
+      end
+
+      def self.allow(message = nil, metadata: nil)
+        new(decision: "allow", message: message, metadata: metadata)
+      end
+
+      def self.deny(message = nil, metadata: nil)
+        new(decision: "deny", message: message, metadata: metadata)
+      end
+
+      def self.ask(message = nil, metadata: nil)
+        new(decision: "ask", message: message, metadata: metadata)
+      end
+
+      def self.modify(payload = nil, message: nil, metadata: nil, **payload_keywords)
+        payload = payload_keywords unless payload_keywords.empty?
+        new(decision: "modify", message: message, payload: payload || {}, metadata: metadata)
+      end
+
+      def self.warn(message = nil, metadata: nil)
+        new(decision: "warn", message: message, metadata: metadata)
+      end
+
+      def self.retry(message = nil, payload: nil, metadata: nil)
+        new(decision: "retry", message: message, payload: payload, metadata: metadata)
+      end
+
+      def self.defer(message = nil, payload: nil, metadata: nil)
+        new(decision: "defer", message: message, payload: payload, metadata: metadata)
+      end
+
+      def self.normalize(value)
+        case value
+        when nil
+          allow
+        when Decision
+          value
+        when String, Symbol
+          new(decision: value)
+        when Hash
+          new(
+            decision: value[:decision] || value["decision"] || "allow",
+            message: value[:message] || value["message"],
+            payload: value[:payload] || value["payload"],
+            metadata: value[:metadata] || value["metadata"]
+          )
+        else
+          raise ArgumentError, "Invalid hook decision: #{value.inspect}"
+        end
+      end
+
+      def allow?
+        decision == "allow"
+      end
+
+      def deny?
+        decision == "deny"
+      end
+
+      def ask?
+        decision == "ask"
+      end
+
+      def modify?
+        decision == "modify"
+      end
+
+      def warning?
+        decision == "warn"
+      end
+
+      def blocking?
+        deny? || ask?
+      end
+
+      def to_h
+        {
+          decision: decision,
+          message: message,
+          payload: payload,
+          metadata: metadata
+        }
+      end
+    end
+  end
+end

data/lib/kward/hooks/event.rb

@@ -0,0 +1,60 @@
+require "securerandom"
+require "time"
+require_relative "../deep_copy"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Immutable lifecycle event delivered to hook handlers.
+    class Event
+      attr_reader :id, :name, :phase, :timestamp, :session, :turn, :workspace, :frontend, :agent, :payload
+
+      def initialize(name:, phase: nil, timestamp: Time.now.utc, session: nil, turn: nil, workspace: nil, frontend: nil, agent: nil, payload: nil, id: nil)
+        @id = id || "hookevt_#{SecureRandom.hex(12)}"
+        @name = name.to_s
+        @phase = phase&.to_s || inferred_phase(@name)
+        @timestamp = timestamp.is_a?(Time) ? timestamp.utc : Time.parse(timestamp.to_s).utc
+        @session = frozen_copy(session || {})
+        @turn = frozen_copy(turn || {})
+        @workspace = frozen_copy(workspace || {})
+        @frontend = frozen_copy(frontend || {})
+        @agent = frozen_copy(agent || {})
+        @payload = frozen_copy(payload || {})
+        freeze
+      end
+
+      def [](key)
+        payload[key] || payload[key.to_s]
+      end
+
+      def to_h
+        {
+          id: id,
+          name: name,
+          phase: phase,
+          timestamp: timestamp.iso8601,
+          session: session,
+          turn: turn,
+          workspace: workspace,
+          frontend: frontend,
+          agent: agent,
+          payload: payload
+        }
+      end
+
+      private
+
+      def inferred_phase(name)
+        return "before" if name.end_with?("_before") || name.include?("before_")
+        return "after" if name.end_with?("_after") || name.include?("after_")
+        return "error" if name.end_with?("_error") || name == "error"
+
+        "during"
+      end
+
+      def frozen_copy(value)
+        DeepCopy.freeze(DeepCopy.dup(value))
+      end
+    end
+  end
+end

data/lib/kward/hooks/http_handler.rb

@@ -0,0 +1,72 @@
+require "json"
+require "net/http"
+require "uri"
+require_relative "catalog"
+require_relative "decision"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Executes an HTTP lifecycle hook using JSON request/response bodies.
+    class HttpHandler
+      DEFAULT_TIMEOUT_SECONDS = 10
+
+      def initialize(url:, timeout_seconds: DEFAULT_TIMEOUT_SECONDS, headers: nil, failure_policy: Catalog::DEFAULT_FAILURE_POLICY, http_client: Net::HTTP)
+        @uri = URI.parse(url.to_s)
+        raise ArgumentError, "HTTP hook requires http or https URL" unless %w[http https].include?(@uri.scheme)
+
+        @timeout_seconds = positive_timeout(timeout_seconds)
+        @headers = stringify_hash(headers || {})
+        @failure_policy = Catalog.normalize_failure_policy(failure_policy)
+        @http_client = http_client
+      end
+
+      def call(event, _context = nil)
+        response = post(JSON.dump(event.to_h))
+        return failure_decision("HTTP hook failed: #{response.code} #{response.message}") unless response.is_a?(Net::HTTPSuccess)
+
+        parse_decision(response.body)
+      rescue StandardError => e
+        failure_decision("HTTP hook failed: #{e.message}")
+      end
+
+      private
+
+      def post(body)
+        request = Net::HTTP::Post.new(@uri)
+        request["Content-Type"] = "application/json"
+        request["Accept"] = "application/json"
+        @headers.each { |key, value| request[key] = value }
+        request.body = body
+
+        @http_client.start(@uri.hostname, @uri.port, use_ssl: @uri.scheme == "https", open_timeout: @timeout_seconds, read_timeout: @timeout_seconds) do |http|
+          http.request(request)
+        end
+      end
+
+      def parse_decision(body)
+        text = body.to_s.strip
+        return Decision.allow if text.empty?
+
+        Decision.normalize(JSON.parse(text))
+      rescue JSON::ParserError => e
+        failure_decision("HTTP hook returned invalid JSON: #{e.message}")
+      end
+
+      def failure_decision(message)
+        Catalog.failure_decision(@failure_policy, message)
+      end
+
+      def positive_timeout(value)
+        seconds = value.to_i
+        seconds.positive? ? seconds : DEFAULT_TIMEOUT_SECONDS
+      end
+
+      def stringify_hash(value)
+        value.each_with_object({}) do |(key, item), result|
+          result[key.to_s] = item.to_s
+        end
+      end
+    end
+  end
+end