kward 0.74.0 → 0.75.0

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

data/lib/kward/hooks/manager.rb

@@ -0,0 +1,158 @@
+require_relative "../deep_copy"
+require_relative "audit_log"
+require_relative "catalog"
+require_relative "decision"
+require_relative "event"
+require_relative "matcher"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Dispatches lifecycle events to registered hooks and combines decisions.
+    class Manager
+      Handler = Struct.new(:id, :event, :source, :order, :match, :callback, :failure_policy, keyword_init: true)
+      Result = Struct.new(:event, :decision, :decisions, :warnings, :messages, :payload, keyword_init: true) do
+        def allowed?
+          !decision.deny? && !decision.ask?
+        end
+
+        def denied?
+          decision.deny?
+        end
+
+        def approval_required?
+          decision.ask?
+        end
+      end
+
+      attr_reader :handlers
+      attr_writer :on_result
+
+      def initialize(audit_log: AuditLog.new, on_result: nil)
+        @handlers = []
+        @audit_log = audit_log
+        @on_result = on_result
+      end
+
+      def register(event, id: nil, source: nil, order: 100, match: nil, failure_policy: nil, &callback)
+        raise ArgumentError, "Hook requires an event name" if event.to_s.empty?
+        raise ArgumentError, "Hook requires a handler" unless callback
+
+        handler = Handler.new(
+          id: id || "#{source || "hook"}:#{event}:#{@handlers.length + 1}",
+          event: event.to_s,
+          source: source,
+          order: order.to_i,
+          match: Matcher.new(match),
+          callback: callback,
+          failure_policy: Catalog.failure_policy(event, failure_policy)
+        )
+        @handlers << handler
+        handler
+      end
+
+      def empty?
+        @handlers.empty?
+      end
+
+      def run(event, context: nil)
+        event = normalize_event(event)
+        decisions = []
+        warnings = []
+        messages = []
+        payload = DeepCopy.dup(event.payload)
+
+        handlers_for(event).each do |handler|
+          decision = call_handler(handler, event, context)
+          decisions << decision
+          warnings << decision.message if decision.warning? && decision.message
+          messages << decision.message if decision.message && !decision.warning?
+
+          if decision.modify?
+            modifications = Catalog.filter_modifications(event.name, decision.payload)
+            payload = DeepCopy.merge(payload, modifications)
+            event = event_with_payload(event, payload)
+          end
+
+          break if decision.deny?
+        end
+
+        final_decision = final_decision(decisions)
+        result = Result.new(
+          event: event,
+          decision: final_decision,
+          decisions: decisions,
+          warnings: warnings,
+          messages: messages,
+          payload: payload
+        )
+        @audit_log&.log_result(event: event, result: result)
+        @on_result&.call(event, result) unless decisions.empty?
+        result
+      end
+
+      private
+
+      def normalize_event(event)
+        return event if event.is_a?(Event)
+
+        Event.new(**event)
+      end
+
+      def handlers_for(event)
+        @handlers
+          .select { |handler| handler.event == event.name && handler.match.match?(event) }
+          .sort_by { |handler| [handler.order, handler.id.to_s] }
+      end
+
+      def call_handler(handler, event, context)
+        started_at = @audit_log&.monotonic_now
+        value = if handler.callback.arity == 1
+                  handler.callback.call(event)
+                else
+                  handler.callback.call(event, context)
+                end
+        Decision.normalize(value).tap do |decision|
+          log_handler(event, handler, decision, started_at)
+        end
+      rescue StandardError => e
+        Catalog.failure_decision(
+          handler.failure_policy,
+          "Hook #{handler.id} failed: #{e.message}",
+          metadata: { hook_id: handler.id, source: handler.source }
+        ).tap do |decision|
+          log_handler(event, handler, decision, started_at)
+        end
+      end
+
+      def log_handler(event, handler, decision, started_at)
+        @audit_log&.log_handler(
+          event: event,
+          handler: handler,
+          decision: decision,
+          duration_ms: started_at ? @audit_log.duration_ms(started_at) : nil
+        )
+      end
+
+      def final_decision(decisions)
+        decisions.find(&:deny?) || decisions.find(&:ask?) || decisions.reverse.find(&:modify?) || decisions.find(&:warning?) || Decision.allow
+      end
+
+      def event_with_payload(event, payload)
+        Event.new(
+          id: event.id,
+          name: event.name,
+          phase: event.phase,
+          timestamp: event.timestamp,
+          session: event.session,
+          turn: event.turn,
+          workspace: event.workspace,
+          frontend: event.frontend,
+          agent: event.agent,
+          payload: payload
+        )
+      end
+
+    end
+  end
+end

data/lib/kward/hooks/matcher.rb

@@ -0,0 +1,75 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Matches lifecycle hook selectors against event payloads.
+    class Matcher
+      def initialize(match = nil)
+        @match = match || {}
+      end
+
+      def match?(event)
+        return true if @match.empty?
+
+        @match.all? { |key, expected| matches_key?(event, key.to_s, expected) }
+      end
+
+      private
+
+      def matches_key?(event, key, expected)
+        case key
+        when "event", "name"
+          matches_value?(event.name, expected)
+        when "phase"
+          matches_value?(event.phase, expected)
+        when "tool", "tool_name"
+          matches_value?(payload_value(event, "tool_name") || payload_value(event, "tool"), expected)
+        when "mcp_server", "server"
+          matches_value?(payload_value(event, "server_name") || payload_value(event, "mcp_server"), expected)
+        when "mcp_tool", "remote_name"
+          matches_value?(payload_value(event, "remote_name") || payload_value(event, "mcp_tool"), expected)
+        when "operation"
+          matches_value?(payload_value(event, "operation"), expected)
+        when "frontend"
+          matches_value?(event.frontend[:name] || event.frontend["name"], expected)
+        when "provider"
+          matches_value?(event.agent[:provider] || event.agent["provider"], expected)
+        when "model"
+          matches_value?(event.agent[:model] || event.agent["model"], expected)
+        when "path", "paths"
+          matches_path?(payload_paths(event), expected)
+        when "command_regex"
+          value = payload_value(event, "command").to_s
+          Array(expected).any? { |pattern| Regexp.new(pattern.to_s).match?(value) }
+        else
+          matches_value?(payload_value(event, key), expected)
+        end
+      end
+
+      def payload_value(event, key)
+        event.payload[key.to_sym] || event.payload[key]
+      end
+
+      def payload_paths(event)
+        values = []
+        values << payload_value(event, "path")
+        values.concat(Array(payload_value(event, "paths")))
+        Array(payload_value(event, "files")).each do |file|
+          values << (file[:path] || file["path"]) if file.respond_to?(:[])
+        end
+        values.compact.map(&:to_s)
+      end
+
+      def matches_path?(paths, expected)
+        patterns = Array(expected).map(&:to_s)
+        paths.any? do |path|
+          patterns.any? { |pattern| File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+        end
+      end
+
+      def matches_value?(actual, expected)
+        expected_values = Array(expected).map(&:to_s)
+        expected_values.include?(actual.to_s)
+      end
+    end
+  end
+end

data/lib/kward/hooks.rb

@@ -0,0 +1,16 @@
+require_relative "hooks/audit_log"
+require_relative "hooks/catalog"
+require_relative "hooks/decision"
+require_relative "hooks/event"
+require_relative "hooks/matcher"
+require_relative "hooks/manager"
+require_relative "hooks/command_handler"
+require_relative "hooks/http_handler"
+require_relative "hooks/config_loader"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Lifecycle hook primitives and dispatch helpers.
+  module Hooks
+  end
+end

data/lib/kward/markdown_transcript.rb

@@ -1,4 +1,5 @@
 require_relative "message_access"
+require_relative "message_text"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -37,10 +38,10 @@ module Kward
     end
 
     def message_display_text(message)
-      display_content = MessageAccess.value(message, :display_content) || MessageAccess.value(message, :displayContent)
-      return display_content.to_s unless display_content.nil?
+      return MessageText.full_text(message) unless MessageAccess.display_content(message).nil?
 
-      markdown_content(MessageAccess.content(message))
+      content = MessageAccess.content(message)
+      content.is_a?(Array) ? markdown_content(content) : MessageText.full_text(message)
     end
 
     def markdown_content(content)

data/lib/kward/mcp/client.rb

@@ -8,7 +8,7 @@ module Kward
 
     # Minimal MCP client for discovering and invoking server tools.
     class Client
-      attr_reader :name
+      attr_reader :name, :transport
 
       def initialize(name:, transport:)
         @name = name.to_s