agent-harness 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50b5bc213cf4a1b6f9441a06a82c38210c7e6907eb085e6cadf71e305e4b7897
-  data.tar.gz: 9785ea0b1b35f5aa52528741ce070287f2d433235ffeaf3d6df0ab7337f486b0
+  metadata.gz: 9e1a243bc20db360b93c22248fd0b35864a995dd6a78def3fdca291d5e39809d
+  data.tar.gz: 591bc4baf70eeb598b4c7a6736b4c0090b7108c6f34628b75a1b5b68eb991805
 SHA512:
-  metadata.gz: 2343d812d85375faad3a55e0462eb228003ff5eddc1920fd1edb75aedf381e5b86e3062c191ee64d24c39f245c1f27ded7d0e74247526727901b6b5391c2518a
-  data.tar.gz: cfe73ff0ffce00f5e0be1726b3dc28d0cdb73aab6546988c19b79846c1d16014476302f2d258d13bb703124edbf86066a96cd43044047ebacc81ad0cf5c853e5
+  metadata.gz: 1028da8c56be8d3f7e948dd23bfd25fbfae3515d1f678fe5c9b5172f5f5a82dbd0fad959ef94d2681619fdf44a6d509dcfc925bc20fb2d3e4e2c92f44ea19d9a
+  data.tar.gz: f8ed1ca7bccfa683eee9303a977920d177a62832b48d937b01c107407890ea60b17680030cf4bc8ca3cd3bdf495def3d90518da89943d55306239ee15869c0c2

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.2"
+  ".": "0.12.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.12.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.11.3...agent-harness/v0.12.0) (2026-05-01)
+
+
+### Features
+
+* streaming JSONL event parser for real-time Codex progress tracking ([#184](https://github.com/viamin/agent-harness/issues/184)) ([4905539](https://github.com/viamin/agent-harness/commit/490553992904f39e52028b2140ab99755aad1fb1))
+
+## [0.11.3](https://github.com/viamin/agent-harness/compare/agent-harness/v0.11.2...agent-harness/v0.11.3) (2026-04-28)
+
+
+### Bug Fixes
+
+* 164: Support provider-agnostic extensions across compatible providers ([#168](https://github.com/viamin/agent-harness/issues/168)) ([2880ae4](https://github.com/viamin/agent-harness/commit/2880ae4f150d1d5574f259b931bbee14ebe0ed04))
+
 ## [0.11.2](https://github.com/viamin/agent-harness/compare/agent-harness/v0.11.1...agent-harness/v0.11.2) (2026-04-27)
 
 

data/lib/agent_harness/configuration.rb

@@ -23,7 +23,7 @@ module AgentHarness
     attr_writer :command_executor
 
     attr_reader :providers, :orchestration_config, :callbacks, :custom_provider_classes
-    attr_reader :sub_agents, :tool_registry, :mcp_servers
+    attr_reader :sub_agents, :tool_registry, :mcp_servers, :extension_registry
 
     def initialize
       @logger = nil # Will use null logger if not set
@@ -40,6 +40,7 @@ module AgentHarness
       @sub_agents = {}
       @tool_registry = ToolRegistry.new
       @mcp_servers = {}
+      @extension_registry = Extensions::Registry.new
     end
 
     # Get or lazily initialize the command executor
@@ -147,6 +148,56 @@ module AgentHarness
       @mcp_servers[name.to_sym] = server
     end
 
+    # Register a provider-agnostic runtime extension.
+    #
+    # @param extension [Extensions::Base] extension instance
+    # @param as [Symbol, String, nil] optional registry key override
+    # @return [Extensions::Base]
+    def register_extension(extension, as: nil)
+      @extension_registry.register(extension, as: as)
+      extension
+    end
+
+    # Load one or more extensions from disk through an adapter.
+    #
+    # @param path [String] extension file, directory, or package root
+    # @param adapter [Symbol, String, nil] optional explicit adapter name
+    # @return [Array<Extensions::Base>]
+    def load_extensions(path, adapter: nil)
+      Extensions::Loader.load(path, adapter: adapter).each do |extension|
+        register_extension(extension)
+      end
+    end
+
+    # Discover and register all extensions found in a directory.
+    #
+    # Each child entry (subdirectory or file) is loaded through the
+    # appropriate adapter; entries that cannot be parsed are silently
+    # skipped.
+    #
+    # @param directory [String] directory to scan
+    # @return [Array<Extensions::Base>]
+    def discover_extensions(directory)
+      Extensions::Loader.discover(directory).each do |extension|
+        register_extension(extension)
+      end
+    end
+
+    # Resolve a registered or inline extension reference.
+    #
+    # @param reference [Symbol, String, Extensions::Base, nil]
+    # @return [Extensions::Base, nil]
+    def resolve_extension(reference)
+      case reference
+      when nil
+        nil
+      when Extensions::Base
+        reference
+      else
+        @extension_registry.fetch(reference)
+      end
+    end
+
     # Resolve a named or inline sub-agent definition.
     #
     # @param reference [Symbol, String, Hash, SubAgentConfig, nil] sub-agent reference

data/lib/agent_harness/errors.rb

@@ -72,6 +72,17 @@ module AgentHarness
   # Configuration errors
   class ConfigurationError < Error; end
 
+  class ExtensionCompatibilityError < ConfigurationError
+    attr_reader :provider, :extension, :report
+
+    def initialize(message = nil, provider: nil, extension: nil, report: nil, **kwargs)
+      @provider = provider
+      @extension = extension
+      @report = report
+      super(message, **kwargs)
+    end
+  end
+
   # MCP-specific errors
   class McpConfigurationError < ConfigurationError; end
 

data/lib/agent_harness/extensions.rb

@@ -0,0 +1,644 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AgentHarness
+  module Extensions
+    module DeepDupable
+      private
+
+      def deep_dup(value)
+        case value
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        when Hash
+          value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+        else
+          value.dup
+        end
+      rescue TypeError
+        value
+      end
+    end
+
+    class Base
+      def name
+        self.class.name.split("::").last&.downcase&.to_sym
+      end
+
+      def description
+        nil
+      end
+
+      def version
+        nil
+      end
+
+      def on_message_before(context)
+        context
+      end
+
+      def on_message_after(context)
+        context
+      end
+
+      def on_tools_available(context)
+        context
+      end
+
+      def tools
+        []
+      end
+
+      def mcp_servers
+        []
+      end
+
+      def system_prompt_additions
+        []
+      end
+
+      def unsupported_features
+        []
+      end
+
+      def required_provider_capabilities
+        required = []
+        required << :tool_use if tools.any?
+        required << :mcp if mcp_servers.any?
+        required
+      end
+    end
+
+    class MessageContext
+      attr_accessor :prompt, :messages, :tools, :options, :response, :metadata
+      attr_reader :provider, :extensions, :mode
+
+      def initialize(provider:, extensions:, mode:, options:, prompt: nil, messages: nil, tools: nil, response: nil,
+        metadata: {})
+        @provider = provider
+        @extensions = extensions.freeze
+        @mode = mode
+        @options = options
+        @prompt = prompt
+        @messages = messages
+        @tools = tools
+        @response = response
+        @metadata = metadata
+      end
+    end
+
+    class CompatibilityReport
+      attr_reader :extension, :provider, :missing_provider_capabilities, :unsupported_features
+
+      def initialize(extension:, provider:, missing_provider_capabilities:, unsupported_features:)
+        @extension = extension
+        @provider = provider
+        @missing_provider_capabilities = missing_provider_capabilities.freeze
+        @unsupported_features = unsupported_features.freeze
+      end
+
+      def compatible?
+        @missing_provider_capabilities.empty?
+      end
+
+      def fully_supported?
+        compatible? && @unsupported_features.empty?
+      end
+
+      def to_h
+        {
+          extension: extension.name,
+          provider: provider.class.provider_name,
+          compatible: compatible?,
+          fully_supported: fully_supported?,
+          missing_provider_capabilities: missing_provider_capabilities.dup,
+          unsupported_features: unsupported_features.dup
+        }
+      end
+    end
+
+    module Compatibility
+      HARNESS_CAPABILITIES = {
+        message_hooks: true,
+        response_hooks: true,
+        system_prompt_additions: true
+      }.freeze
+
+      module_function
+
+      def report(provider:, extension:)
+        required = Array(extension.required_provider_capabilities).map(&:to_sym)
+        missing = required.reject { |capability| capability_supported?(provider, capability) }
+        unsupported = Array(extension.unsupported_features).map(&:to_sym)
+
+        CompatibilityReport.new(
+          extension: extension,
+          provider: provider,
+          missing_provider_capabilities: missing,
+          unsupported_features: unsupported
+        )
+      end
+
+      def check!(provider:, extension:, strict: true)
+        compatibility = report(provider: provider, extension: extension)
+        return compatibility if compatibility.compatible?
+        return compatibility unless strict
+
+        raise ExtensionCompatibilityError.new(
+          "Extension '#{extension.name}' is not compatible with provider '#{provider.class.provider_name}': " \
+          "missing provider capabilities: #{compatibility.missing_provider_capabilities.inspect}",
+          provider: provider.class.provider_name,
+          extension: extension.name,
+          report: compatibility.to_h
+        )
+      end
+
+      def capability_supported?(provider, capability)
+        return HARNESS_CAPABILITIES.fetch(capability) if HARNESS_CAPABILITIES.key?(capability)
+
+        case capability
+        when :chat
+          provider.supports_chat?
+        when :text_mode
+          provider.supports_text_mode?
+        else
+          !!provider.capabilities[capability]
+        end
+      end
+    end
+
+    module Composition
+      module_function
+
+      def compose(extensions)
+        return [] if extensions.nil? || extensions.empty?
+
+        detect_tool_conflicts(extensions)
+        extensions
+      end
+
+      def detect_tool_conflicts(extensions)
+        tool_owners = {}
+
+        extensions.each do |extension|
+          extension.tools.each do |tool|
+            tool_name = tool[:name] || tool["name"]
+            next unless tool_name
+
+            if tool_owners.key?(tool_name)
+              raise ConfigurationError,
+                "Tool name conflict: '#{tool_name}' is provided by both " \
+                "'#{tool_owners[tool_name]}' and '#{extension.name}'"
+            end
+
+            tool_owners[tool_name] = extension.name
+          end
+        end
+      end
+
+      def merge_system_prompts(extensions)
+        extensions.flat_map(&:system_prompt_additions).reject { |a| a.nil? || a.empty? }
+      end
+
+      def merge_tools(extensions)
+        extensions.flat_map(&:tools)
+      end
+
+      def merge_mcp_servers(extensions)
+        servers = extensions.flat_map(&:mcp_servers)
+        names = servers.map { |s| s[:name] || s["name"] }.compact
+        duplicates = names.group_by { |n| n }.select { |_, v| v.size > 1 }.keys
+
+        unless duplicates.empty?
+          raise ConfigurationError,
+            "MCP server name conflict across extensions: #{duplicates.join(", ")}"
+        end
+
+        servers
+      end
+    end
+
+    class Registry
+      def initialize
+        @extensions = {}
+      end
+
+      def register(extension, as: nil)
+        unless extension.is_a?(Base)
+          raise ConfigurationError, "Extension must be an AgentHarness::Extensions::Base instance"
+        end
+
+        key = (as || extension.name).to_sym
+        @extensions[key] = extension
+      end
+
+      def fetch(name)
+        @extensions.fetch(name.to_sym) do
+          raise ConfigurationError, "Unknown extension: #{name}"
+        end
+      end
+
+      def registered?(name)
+        @extensions.key?(name.to_sym)
+      end
+
+      def all
+        @extensions.values.dup
+      end
+    end
+
+    module Loader
+      module_function
+
+      def load(path, adapter: nil)
+        resolved_path = File.expand_path(path)
+        adapter_name = normalize_adapter(adapter, resolved_path)
+
+        case adapter_name
+        when :pi
+          Adapters::Pi.load(resolved_path)
+        when :skill
+          Adapters::Skill.load(resolved_path)
+        else
+          raise ConfigurationError, "Unknown extension adapter: #{adapter_name.inspect}"
+        end
+      end
+
+      def normalize_adapter(adapter, path)
+        return adapter.to_sym if adapter
+        return :pi if File.directory?(path) && pi_directory?(path)
+        return :pi if File.file?(path) && File.extname(path).match?(/\A\.(?:[jt]s|json)\z/i)
+        return :skill if File.file?(path) && File.extname(path) == ".md"
+        if File.directory?(path)
+          raise ConfigurationError, "Cannot infer extension adapter for directory: #{path}"
+        end
+
+        raise ConfigurationError, "Could not infer adapter for extension source: #{path}"
+      end
+
+      def pi_directory?(path)
+        return true if File.exist?(File.join(path, "package.json"))
+        return true if File.exist?(File.join(path, "index.ts")) || File.exist?(File.join(path, "index.js"))
+        return true if File.directory?(File.join(path, "extensions"))
+        # Detect bare Pi-style directories containing .ts/.js source files
+        # even without package.json or index.ts, since Pi.load can resolve them.
+        return true if Dir.glob(File.join(path, "*.{ts,js}")).any?
+
+        false
+      end
+
+      def discover(directory)
+        resolved = File.expand_path(directory)
+        return [] unless File.directory?(resolved)
+
+        extensions = []
+
+        Dir.glob(File.join(resolved, "*")).sort.each do |child|
+          next unless File.directory?(child) || File.file?(child)
+
+          begin
+            extensions.concat(load(child))
+          rescue ConfigurationError
+            next
+          end
+        end
+
+        extensions
+      end
+    end
+
+    module Adapters
+      class PiExtension < Base
+        include DeepDupable
+
+        attr_reader :name, :description, :version, :entry_paths, :source_path
+
+        def initialize(name:, source_path:, entry_paths:, description: nil, version: nil, tools: [],
+          system_prompt_additions: [], mcp_servers: [], required_provider_capabilities: [],
+          unsupported_features: [])
+          @name = name.to_s.strip.gsub(/[^a-zA-Z0-9]+/, "_").gsub(/\A_+|_+\z/, "").downcase.to_sym
+          @description = description
+          @version = version
+          @tools = tools.freeze
+          @system_prompt_additions = system_prompt_additions.freeze
+          @mcp_servers = mcp_servers.freeze
+          @required_provider_capabilities = required_provider_capabilities.freeze
+          @unsupported_features = unsupported_features.freeze
+          @source_path = source_path
+          @entry_paths = entry_paths.freeze
+        end
+
+        def tools
+          @tools.map(&:dup)
+        end
+
+        def mcp_servers
+          @mcp_servers.map { |server| deep_dup(server) }
+        end
+
+        def system_prompt_additions
+          @system_prompt_additions.dup
+        end
+
+        def required_provider_capabilities
+          inferred = []
+          inferred << :tool_use if @tools.any?
+          inferred << :mcp if @mcp_servers.any?
+          (@required_provider_capabilities + inferred).uniq
+        end
+
+        def unsupported_features
+          @unsupported_features.dup
+        end
+      end
+
+      module Pi
+        module_function
+
+        def load(path)
+          resolved_path = File.expand_path(path)
+          single_file = File.file?(resolved_path) && %w[.ts .js].include?(File.extname(resolved_path)) &&
+            File.basename(resolved_path) != "package.json"
+
+          root = resolve_root(resolved_path)
+          package = load_package_json(root)
+          entry_paths = if single_file
+            # When a specific script file is requested, scope to that file only
+            # instead of discovering all siblings in the parent directory.
+            [resolved_path]
+          else
+            discover_entry_paths(root, package)
+          end
+          ext_config = package.fetch("agent_harness", {})
+          tools = ext_config["tools"] || discover_tools(entry_paths)
+          system_prompt_additions = Array(ext_config["system_prompt_additions"])
+          mcp_servers = Array(ext_config["mcp_servers"])
+          required_provider_capabilities = Array(ext_config["required_provider_capabilities"])
+          # Conservatively require :tool_use when registerTool is called with non-inline
+          # arguments that static extraction cannot parse.
+          if !ext_config["tools"] && has_non_inline_register_tool_calls?(entry_paths)
+            required_provider_capabilities |= ["tool_use"]
+          end
+          unsupported_features = Array(ext_config["unsupported_features"])
+          unsupported_features |= infer_unsupported_features(entry_paths)
+
+          default_name = single_file ? File.basename(resolved_path, File.extname(resolved_path)) : File.basename(root)
+
+          [
+            PiExtension.new(
+              name: ext_config["name"] || package["name"] || default_name,
+              description: ext_config["description"] || package["description"],
+              version: ext_config["version"] || package["version"],
+              tools: tools.map { |tool| normalize_tool(tool) },
+              system_prompt_additions: system_prompt_additions,
+              mcp_servers: mcp_servers.map { |server| normalize_mcp_server(server) },
+              required_provider_capabilities: required_provider_capabilities.map(&:to_sym),
+              unsupported_features: unsupported_features.map(&:to_sym),
+              source_path: root,
+              entry_paths: entry_paths
+            )
+          ]
+        end
+
+        def resolve_root(path)
+          if File.file?(path)
+            return File.dirname(path) if File.basename(path) == "package.json"
+            return File.dirname(path) if %w[.ts .js].include?(File.extname(path))
+          end
+
+          return path if File.directory?(path)
+
+          raise ConfigurationError, "Unsupported pi extension source: #{path}"
+        end
+
+        def load_package_json(root)
+          package_path = File.join(root, "package.json")
+          return {} unless File.exist?(package_path)
+
+          JSON.parse(File.read(package_path))
+        rescue JSON::ParserError => e
+          raise ConfigurationError, "Invalid package.json for pi extension at #{root}: #{e.message}"
+        end
+
+        def discover_entry_paths(root, package)
+          manifest_entries = Array(package.dig("pi", "extensions"))
+          candidates = if manifest_entries.empty?
+            convention_extension_paths(root)
+          else
+            manifest_entries.flat_map { |entry| expand_manifest_entry(root, entry) }
+          end
+
+          paths = candidates.select { |candidate| File.file?(candidate) }
+          raise ConfigurationError, "No pi extension entry points found in #{root}" if paths.empty?
+
+          paths.uniq.sort
+        end
+
+        def convention_extension_paths(root)
+          extensions_dir = File.join(root, "extensions")
+          return direct_extension_entry_paths(root) unless File.directory?(extensions_dir)
+
+          direct_extension_entry_paths(extensions_dir)
+        end
+
+        def expand_manifest_entry(root, entry)
+          absolute = File.expand_path(entry, root)
+          return direct_extension_entry_paths(absolute) if File.directory?(absolute)
+          return Dir.glob(absolute).flat_map { |match| direct_extension_entry_paths(match) } unless File.exist?(absolute)
+
+          direct_extension_entry_paths(absolute)
+        end
+
+        def direct_extension_entry_paths(path)
+          if File.file?(path)
+            return [path] if extension_script?(path)
+            return []
+          end
+
+          return [] unless File.directory?(path)
+
+          entries = []
+          entries.concat(Dir.glob(File.join(path, "*.{ts,js}")))
+          Dir.glob(File.join(path, "*")).sort.each do |child|
+            next unless File.directory?(child)
+
+            %w[index.ts index.js].each do |entry|
+              entry_path = File.join(child, entry)
+              entries << entry_path if File.file?(entry_path)
+            end
+          end
+          entries
+        end
+
+        def extension_script?(path)
+          %w[.ts .js].include?(File.extname(path))
+        end
+
+        def discover_tools(entry_paths)
+          entry_paths.flat_map do |entry_path|
+            source = File.read(entry_path)
+            source.scan(/registerTool\s*\(\s*\{(.*?)\}\s*\)/m).filter_map do |match|
+              block = match.first
+              name = block[/name:\s*["']([^"']+)["']/, 1]
+              next unless name
+
+              description = block[/description:\s*["']([^"']+)["']/, 1]
+              {name: name, description: description}.compact
+            end
+          end.uniq
+        end
+
+        # Detect whether any entry path contains registerTool calls that could
+        # not be statically extracted as inline object literals. When true, the
+        # extension should conservatively require :tool_use even if discover_tools
+        # returned an empty list.
+        def has_non_inline_register_tool_calls?(entry_paths)
+          entry_paths.any? do |entry_path|
+            source = File.read(entry_path)
+            total_calls = source.scan(/registerTool\s*\(/).length
+            inline_calls = source.scan(/registerTool\s*\(\s*\{/).length
+            total_calls > inline_calls
+          end
+        end
+
+        def infer_unsupported_features(entry_paths)
+          features = []
+
+          entry_paths.each do |entry_path|
+            source = File.read(entry_path)
+            features << :commands if source.include?("registerCommand")
+            features << :shortcuts if source.include?("registerShortcut")
+            features << :ui if source.match?(/ctx\.ui\.|setWidget|setStatus|setTitle/)
+            features << :session_persistence if source.match?(/appendEntry|session_start|session_end/)
+          end
+
+          features.uniq
+        end
+
+        def normalize_tool(tool)
+          case tool
+          when Hash
+            tool.transform_keys(&:to_sym)
+          when String, Symbol
+            {name: tool.to_s}
+          else
+            raise ConfigurationError, "Unsupported tool definition in pi adapter: #{tool.inspect}"
+          end
+        end
+
+        def normalize_mcp_server(server)
+          case server
+          when Hash
+            server.transform_keys(&:to_sym)
+          else
+            raise ConfigurationError, "Unsupported MCP server definition in pi adapter: #{server.inspect}"
+          end
+        end
+      end
+
+      class SkillExtension < Base
+        include DeepDupable
+
+        attr_reader :name, :description, :version, :source_path
+
+        def initialize(name:, source_path:, description: nil, version: nil, tools: [],
+          system_prompt_additions: [], mcp_servers: [], required_provider_capabilities: [])
+          @name = name.to_s.strip.gsub(/[^a-zA-Z0-9]+/, "_").gsub(/\A_+|_+\z/, "").downcase.to_sym
+          @description = description
+          @version = version
+          @tools = tools.freeze
+          @system_prompt_additions = system_prompt_additions.freeze
+          @mcp_servers = mcp_servers.freeze
+          @required_provider_capabilities = required_provider_capabilities.freeze
+          @source_path = source_path
+        end
+
+        def tools
+          @tools.map(&:dup)
+        end
+
+        def mcp_servers
+          @mcp_servers.map { |server| deep_dup(server) }
+        end
+
+        def system_prompt_additions
+          @system_prompt_additions.dup
+        end
+
+        def required_provider_capabilities
+          inferred = []
+          inferred << :tool_use if @tools.any?
+          inferred << :mcp if @mcp_servers.any?
+          (@required_provider_capabilities + inferred).uniq
+        end
+      end
+
+      module Skill
+        module_function
+
+        def load(path)
+          resolved = File.expand_path(path)
+          raise ConfigurationError, "Skill file not found: #{resolved}" unless File.file?(resolved)
+          raise ConfigurationError, "Skill file must be a Markdown file: #{resolved}" unless File.extname(resolved) == ".md"
+
+          content = File.read(resolved)
+          frontmatter, body = parse_frontmatter(content)
+
+          tools = Array(frontmatter["tools"]).map { |tool| normalize_tool(tool) }
+          mcp_servers = Array(frontmatter["mcp_servers"]).map { |server| normalize_mcp_server(server) }
+          instructions = extract_instructions(body)
+          system_prompt_additions = instructions.empty? ? [] : [instructions]
+
+          [
+            SkillExtension.new(
+              name: frontmatter["name"] || File.basename(resolved, ".md"),
+              description: frontmatter["description"],
+              version: frontmatter["version"],
+              tools: tools,
+              system_prompt_additions: system_prompt_additions,
+              mcp_servers: mcp_servers,
+              required_provider_capabilities: Array(frontmatter["required_provider_capabilities"]).map(&:to_sym),
+              source_path: resolved
+            )
+          ]
+        end
+
+        def parse_frontmatter(content)
+          match = content.match(/\A---\s*\n(.*?\n)---\s*\n(.*)\z/m)
+          return [{}, content] unless match
+
+          require "yaml"
+          frontmatter = YAML.safe_load(match[1], permitted_classes: [Symbol]) || {}
+          [frontmatter, match[2]]
+        rescue Psych::SyntaxError => e
+          raise ConfigurationError, "Invalid YAML frontmatter in skill file: #{e.message}"
+        end
+
+        def extract_instructions(body)
+          body.to_s.strip
+        end
+
+        def normalize_tool(tool)
+          case tool
+          when Hash
+            tool.transform_keys(&:to_sym)
+          when String, Symbol
+            {name: tool.to_s}
+          else
+            raise ConfigurationError, "Unsupported tool definition in skill adapter: #{tool.inspect}"
+          end
+        end
+
+        def normalize_mcp_server(server)
+          case server
+          when Hash
+            server.transform_keys(&:to_sym)
+          else
+            raise ConfigurationError, "Unsupported MCP server definition in skill adapter: #{server.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/providers/base.rb

@@ -25,6 +25,7 @@ module AgentHarness
     #   end
     class Base
       include Adapter
+      include Extensions::DeepDupable
 
       DEFAULT_SMOKE_TEST_CONTRACT = {
         prompt: "Reply with exactly OK.",
@@ -76,9 +77,11 @@ module AgentHarness
       # @param config [ProviderConfig, nil] provider configuration
       # @param executor [CommandExecutor, nil] command executor
       # @param logger [Logger, nil] logger instance
-      def initialize(config: nil, executor: nil, logger: nil)
+      # @param configuration [Configuration, nil] parent configuration for extension/sub-agent resolution
+      def initialize(config: nil, executor: nil, logger: nil, configuration: nil)
         @config = config || ProviderConfig.new(self.class.provider_name)
-        @executor = executor || AgentHarness.configuration.command_executor
+        @configuration = configuration || AgentHarness.configuration
+        @executor = executor || @configuration.command_executor
         @logger = logger || AgentHarness.logger
       end
 
@@ -126,6 +129,15 @@ module AgentHarness
 
         # Coerce provider_runtime from Hash if needed
         options = normalize_provider_runtime(options)
+
+        # Capture execution options (callbacks, observer) before extensions
+        # processing deep-dups the options hash, which would replace identity-
+        # sensitive references (observers, procs) with clones.
+        exec_opts = command_execution_options(options)
+
+        extension_context = apply_extensions_to_prompt(prompt, options)
+        prompt = extension_context.prompt
+        options = extension_context.options
         options = normalize_sub_agent(options)
         prompt = apply_sub_agent_to_prompt(prompt, options[:translated_sub_agent])
 
@@ -147,7 +159,7 @@ module AgentHarness
           timeout: timeout,
           env: build_env(options),
           preparation: preparation,
-          **command_execution_options(options)
+          **exec_opts
         )
         duration = Time.now - start_time
 
@@ -171,13 +183,15 @@ module AgentHarness
           )
         end
 
+        response = apply_extensions_after_response(extension_context, response)
+
         # Track tokens
         track_tokens(response) if response.tokens
 
         log_debug("send_message_complete", duration: duration, tokens: response.tokens)
 
         response
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ExtensionCompatibilityError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -220,7 +234,12 @@ module AgentHarness
 
         transport = resolve_chat_transport(options)
         messages = format_messages_for_transport(conversation, transport)
+        extension_context = apply_extensions_to_chat(messages, tools, options)
+        messages = extension_context.messages
+        tools = extension_context.tools
+        options = extension_context.options
         messages = apply_sub_agent_to_messages(messages, options[:translated_sub_agent])
+        validate_chat_mcp_servers!(options[:mcp_servers])
         transport_opts = chat_transport_options(runtime, options)
         transport_opts[:on_chat_chunk] = on_chat_chunk if on_chat_chunk
         transport_opts[:observer] = observer if observer
@@ -233,11 +252,13 @@ module AgentHarness
           &on_chunk
         )
 
+        response = apply_extensions_after_response(extension_context, response)
+
         track_tokens(response) if response.tokens
         log_debug("send_chat_message_complete", duration: response.duration, tokens: response.tokens)
 
         response
-      rescue ProviderError, AuthenticationError, RateLimitError, TimeoutError
+      rescue ExtensionCompatibilityError, ProviderError, AuthenticationError, RateLimitError, TimeoutError
         raise
       rescue => e
         last_msg = conversation&.last || messages&.last
@@ -423,7 +444,7 @@ module AgentHarness
           servers = options[:mcp_servers]
         else
           # Configuration stores mcp_servers as a Hash keyed by name; extract values.
-          config_servers = AgentHarness.configuration.mcp_servers
+          config_servers = @configuration.mcp_servers
           servers = config_servers.is_a?(Hash) ? config_servers.values : config_servers
         end
         return options if servers.nil?
@@ -460,12 +481,12 @@ module AgentHarness
         sub_agent = options[:sub_agent]
         return options unless sub_agent
 
-        resolved = AgentHarness.configuration.resolve_sub_agent(sub_agent)
+        resolved = @configuration.resolve_sub_agent(sub_agent)
         translated = SubAgentTranslator.for_provider(
           self.class.provider_name,
           resolved,
-          tool_registry: AgentHarness.configuration.tool_registry,
-          mcp_servers: AgentHarness.configuration.mcp_servers
+          tool_registry: @configuration.tool_registry,
+          mcp_servers: @configuration.mcp_servers
         )
 
         options.merge(sub_agent: resolved, translated_sub_agent: translated)
@@ -483,6 +504,182 @@ module AgentHarness
         [{role: "system", content: translated_sub_agent[:runtime_instructions]}] + messages
       end
 
+      def resolve_extensions(options)
+        Array(options[:extensions]).filter_map do |reference|
+          @configuration.resolve_extension(reference)
+        end
+      end
+
+      def apply_extensions_to_prompt(prompt, options)
+        extensions = resolve_extensions(options)
+        strict = options.fetch(:extensions_strict, true)
+        Extensions::Composition.compose(extensions) if extensions.size > 1
+        context = Extensions::MessageContext.new(
+          provider: self,
+          extensions: extensions,
+          mode: :message,
+          prompt: prompt,
+          options: deep_dup(options),
+          metadata: {}
+        )
+
+        validate_extensions!(extensions, strict: strict)
+        reject_tool_extensions_in_message_mode!(extensions)
+        reject_mcp_extensions_in_message_mode!(extensions)
+        apply_extension_system_prompt!(context)
+        extensions.each { |extension| extension.on_message_before(context) }
+        context
+      end
+
+      def apply_extensions_to_chat(messages, tools, options)
+        extensions = resolve_extensions(options)
+        strict = options.fetch(:extensions_strict, true)
+        Extensions::Composition.compose(extensions) if extensions.size > 1
+        context = Extensions::MessageContext.new(
+          provider: self,
+          extensions: extensions,
+          mode: :chat,
+          messages: deep_dup(messages),
+          tools: merge_extension_tools(tools, extensions),
+          options: deep_dup(options),
+          metadata: {}
+        )
+
+        validate_extensions!(extensions, strict: strict)
+        merge_extension_mcp_servers!(context)
+        apply_extension_system_messages!(context)
+        extensions.each { |extension| extension.on_message_before(context) }
+        extensions.each { |extension| extension.on_tools_available(context) } if context.tools&.any?
+        context
+      end
+
+      def apply_extensions_after_response(context, response)
+        return response unless context
+
+        context.response = response
+        context.extensions.each { |extension| extension.on_message_after(context) }
+        context.response
+      end
+
+      def validate_extensions!(extensions, strict: true)
+        extensions.each do |extension|
+          report = Extensions::Compatibility.check!(provider: self, extension: extension, strict: strict)
+          next if report.fully_supported?
+
+          @logger&.warn(
+            "[AgentHarness::#{self.class.provider_name}] Extension '#{extension.name}' has " \
+            "unsupported features that will be unavailable: #{report.unsupported_features.inspect}"
+          )
+        end
+      end
+
+      def validate_chat_mcp_servers!(mcp_servers)
+        return if mcp_servers.nil? || mcp_servers.empty?
+
+        # Chat transports do not support request-scoped MCP servers.
+        # Raise early so extensions with MCP requirements are not silently ignored.
+        raise McpUnsupportedError.new(
+          "Chat mode does not support request-scoped MCP servers. " \
+          "Extensions or options requiring MCP servers cannot be used with send_chat_message.",
+          provider: self.class.provider_name
+        )
+      end
+
+      def reject_tool_extensions_in_message_mode!(extensions)
+        tool_extensions = extensions.select { |ext| ext.tools.any? }
+        return if tool_extensions.empty?
+
+        names = tool_extensions.map(&:name).join(", ")
+        raise ExtensionCompatibilityError.new(
+          "Extensions with tools are not supported in message mode (CLI execution " \
+          "cannot accept dynamic tool definitions): #{names}",
+          provider: self.class.provider_name
+        )
+      end
+
+      def reject_mcp_extensions_in_message_mode!(extensions)
+        mcp_extensions = extensions.select { |ext| ext.mcp_servers.any? }
+        return if mcp_extensions.empty?
+
+        names = mcp_extensions.map(&:name).join(", ")
+        raise ExtensionCompatibilityError.new(
+          "Extensions with MCP servers are not supported in message mode: #{names}",
+          provider: self.class.provider_name
+        )
+      end
+
+      def merge_extension_mcp_servers!(context)
+        extension_servers = context.extensions.flat_map(&:mcp_servers)
+        return if extension_servers.empty?
+
+        merged = Array(context.options[:mcp_servers]) + extension_servers
+        context.options = context.options.merge(mcp_servers: merged)
+      end
+
+      def merge_extension_tools(tools, extensions)
+        extension_tools = extensions.flat_map(&:tools)
+        return tools unless extension_tools.any?
+
+        normalized_extension_tools = extension_tools.map { |t| normalize_extension_tool_for_provider(t) }
+        merged = Array(tools) + normalized_extension_tools
+        names = merged.map { |t| extract_tool_name(t) }.compact
+        duplicates = names.group_by { |n| n }.select { |_, v| v.size > 1 }.keys
+        unless duplicates.empty?
+          raise ConfigurationError,
+            "Tool name conflict between user-provided and extension tools: #{duplicates.join(", ")}"
+        end
+        merged
+      end
+
+      def extract_tool_name(tool)
+        tool[:name] || tool["name"] ||
+          tool.dig(:function, :name) || tool.dig(:function, "name") ||
+          tool.dig("function", "name") || tool.dig("function", :name)
+      end
+
+      def normalize_extension_tool_for_provider(tool)
+        case chat_transport_type
+        when :openai_compatible
+          # OpenAI-style: {type: "function", function: {name: ..., description: ...}}
+          return tool if tool[:type] == "function" || tool["type"] == "function"
+
+          func = {name: tool[:name] || tool["name"]}
+          description = tool[:description] || tool["description"]
+          func[:description] = description if description
+          parameters = tool[:parameters] || tool["parameters"]
+          func[:parameters] = parameters if parameters
+          {type: "function", function: func}
+        else
+          # Anthropic-style: {name: ..., description: ..., input_schema: ...}
+          # Convert `parameters` key to `input_schema` for Anthropic/TextTransport compatibility.
+          normalized = tool.dup
+          params = normalized.delete(:parameters) || normalized.delete("parameters")
+          if params && !normalized.key?(:input_schema) && !normalized.key?("input_schema")
+            normalized[:input_schema] = params
+          end
+          normalized
+        end
+      end
+
+      def apply_extension_system_prompt!(context)
+        additions = context.extensions.flat_map(&:system_prompt_additions).reject do |addition|
+          addition.nil? || addition.empty?
+        end
+        return if additions.empty?
+
+        context.prompt = [additions.join("\n\n"), context.prompt].join("\n\n")
+      end
+
+      def apply_extension_system_messages!(context)
+        additions = context.extensions.flat_map(&:system_prompt_additions).reject do |addition|
+          addition.nil? || addition.empty?
+        end
+        return if additions.empty?
+
+        system_messages = additions.map { |addition| {role: "system", content: addition} }
+        context.messages = system_messages + context.messages
+      end
+
       def command_execution_options(options)
         execution_options = {
           idle_timeout: options[:idle_timeout],

data/lib/agent_harness/providers/codex.rb

@@ -11,6 +11,11 @@ module AgentHarness
       include RateLimitResetParsing
       include McpConfigFileSupport
 
+      StreamingEvent = Struct.new(
+        :type, :turn, :tokens, :error_message, :tool_name, :raw_event,
+        keyword_init: true
+      )
+
       SUPPORTED_CLI_VERSION = "0.116.0"
       SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.117.0").freeze
       OAUTH_REFRESH_FAILURE_PATTERNS = [
@@ -142,15 +147,31 @@ module AgentHarness
         end
 
         def parse_cli_jsonl_transcript(raw_output, max_events: nil)
-          return new.send(:parse_jsonl_output, "") if max_events && max_events <= 0
+          return parser_instance.send(:parse_jsonl_output, "") if max_events && max_events <= 0
 
           output = max_events ? tail_nonempty_lines(raw_output, limit: max_events).join("\n") : raw_output
 
-          new.send(:parse_jsonl_output, output)
+          parser_instance.send(:parse_jsonl_output, output)
+        end
+
+        # Parse a single Codex JSONL event as it arrives on stdout and classify it
+        # for real-time progress tracking. Returns nil for malformed JSON, scalar
+        # JSON values, plain-text output, or unsupported event types.
+        def parse_streaming_event(line)
+          event = JSON.parse(line.to_s)
+          return unless event.is_a?(Hash)
+
+          parser_instance.send(:build_streaming_event, event)
+        rescue JSON::ParserError, TypeError
+          nil
         end
 
         private
 
+        def parser_instance
+          @parser_instance ||= allocate.freeze
+        end
+
         def tail_nonempty_lines(text, limit:)
           return [] if limit <= 0
 
@@ -507,6 +528,152 @@ module AgentHarness
 
       private
 
+      def build_streaming_event(event)
+        raw_event, payload, dispatch_type = unwrap_streaming_event(event)
+        return unless payload.is_a?(Hash)
+
+        case dispatch_type
+        when "message.delta", "agent_message_delta"
+          build_progress_streaming_event(raw_event, payload)
+        when "turn.completed", "task_complete", "turn_complete"
+          build_turn_complete_streaming_event(raw_event, payload)
+        when "turn.failed"
+          build_error_streaming_event(raw_event, payload)
+        when "item.completed", "response_item", "agent_message"
+          build_item_streaming_event(raw_event, payload)
+        when "token_count"
+          build_token_usage_streaming_event(raw_event, payload)
+        end
+      end
+
+      def unwrap_streaming_event(event)
+        event_type = event["type"]
+
+        if event_type == "event_msg"
+          payload = event["payload"]
+          [event, payload, payload.is_a?(Hash) ? payload["type"] : nil]
+        elsif event_type == "response_item"
+          # Preserve the original "response_item" dispatch type so
+          # build_streaming_event routes to build_item_streaming_event
+          # even after unwrapping the inner payload.
+          [event, event["payload"], "response_item"]
+        else
+          [event, event, event_type]
+        end
+      end
+
+      def build_progress_streaming_event(raw_event, payload)
+        return unless progress_payload?(payload)
+
+        StreamingEvent.new(
+          type: :progress,
+          turn: extract_streaming_turn(payload),
+          raw_event: raw_event
+        )
+      end
+
+      def build_turn_complete_streaming_event(raw_event, payload)
+        StreamingEvent.new(
+          type: :turn_complete,
+          turn: extract_streaming_turn(payload),
+          tokens: compact_streaming_tokens(build_token_usage(payload["usage"])),
+          raw_event: raw_event
+        )
+      end
+
+      def build_error_streaming_event(raw_event, payload)
+        StreamingEvent.new(
+          type: :error,
+          turn: extract_streaming_turn(payload),
+          tokens: compact_streaming_tokens(build_token_usage(payload["usage"])),
+          error_message: extract_error_message(payload),
+          raw_event: raw_event
+        )
+      end
+
+      def build_item_streaming_event(raw_event, payload)
+        item = payload["item"].is_a?(Hash) ? payload["item"] : payload
+
+        if tool_use_payload?(item)
+          return StreamingEvent.new(
+            type: :tool_use,
+            turn: extract_streaming_turn(payload),
+            tool_name: extract_tool_name(item),
+            raw_event: raw_event
+          )
+        end
+
+        return unless assistant_message_item?(item) || response_item_assistant_payload?(item) || wrapped_assistant_payload?(item)
+
+        StreamingEvent.new(
+          type: :progress,
+          turn: extract_streaming_turn(payload),
+          raw_event: raw_event
+        )
+      end
+
+      def build_token_usage_streaming_event(raw_event, payload)
+        wrapped_token_usage = extract_wrapped_tokens(payload["info"])
+        usage = wrapped_token_usage&.fetch(:last, nil) || wrapped_token_usage&.fetch(:total, nil)
+        return unless usage
+
+        StreamingEvent.new(
+          type: :token_usage,
+          turn: extract_streaming_turn(payload),
+          tokens: compact_streaming_tokens(usage),
+          raw_event: raw_event
+        )
+      end
+
+      def progress_payload?(payload)
+        case payload["type"]
+        when "message.delta"
+          payload["delta"].is_a?(Hash)
+        when "agent_message_delta"
+          wrapped_assistant_payload?(payload)
+        else
+          false
+        end
+      end
+
+      def tool_use_payload?(item)
+        item.is_a?(Hash) && item["type"] == "tool_call"
+      end
+
+      def extract_tool_name(item)
+        item["tool_name"] || item["name"] || item.dig("function", "name") || item.dig("call", "name")
+      end
+
+      def extract_streaming_turn(payload)
+        value = payload["turn"] || payload["turn_id"] || payload["turn_index"] || payload.dig("context", "turn")
+        return value if value.is_a?(Integer)
+
+        value.to_i if value.is_a?(String) && /\A\d+\z/.match?(value.strip)
+      end
+
+      def compact_streaming_tokens(usage)
+        return unless usage
+
+        {
+          input: usage[:input],
+          output: usage[:output],
+          total: usage[:total]
+        }
+      end
+
+      def extract_error_message(payload)
+        error = payload["error"]
+
+        case error
+        when String
+          error
+        when Hash
+          error["message"] || error["error"] || error["detail"]
+        else
+          payload["message"]
+        end
+      end
+
       def escape_toml_string(val)
         val.to_s.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }
       end

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.11.2"
+  VERSION = "0.12.0"
 end

data/lib/agent_harness.rb

@@ -77,6 +77,47 @@ module AgentHarness
       conductor.send_message(prompt, provider: provider, executor: executor, **options)
     end
 
+    # Resolve a canonical extension definition by name or inline object.
+    #
+    # @param reference [Symbol, String, Extensions::Base]
+    # @return [Extensions::Base]
+    def extension(reference)
+      configuration.resolve_extension(reference)
+    end
+
+    # Load one or more extensions from disk through an adapter.
+    #
+    # @param path [String] extension file, directory, or package root
+    # @param adapter [Symbol, String, nil] optional explicit adapter
+    # @return [Array<Extensions::Base>]
+    def load_extensions(path, adapter: nil)
+      configuration.load_extensions(path, adapter: adapter)
+    end
+
+    # Discover and register all extensions found in a directory.
+    #
+    # @param directory [String] directory to scan
+    # @return [Array<Extensions::Base>]
+    def discover_extensions(directory)
+      configuration.discover_extensions(directory)
+    end
+
+    # Build a compatibility report for extensions against a provider.
+    #
+    # @param provider [Symbol, String, Providers::Base] target provider
+    # @param extensions [Array<Symbol, String, Extensions::Base>] extension references
+    # @return [Array<Extensions::CompatibilityReport>]
+    def extension_compatibility(provider:, extensions:)
+      provider_instance = provider.is_a?(Providers::Base) ? provider : self.provider(provider)
+
+      Array(extensions).map do |extension_ref|
+        Extensions::Compatibility.report(
+          provider: provider_instance,
+          extension: extension(extension_ref)
+        )
+      end
+    end
+
     # Resolve a canonical sub-agent definition by name or inline payload.
     #
     # @param reference [Symbol, String, Hash, SubAgentConfig]
@@ -277,6 +318,7 @@ end
 
 # Core components
 require_relative "agent_harness/errors"
+require_relative "agent_harness/extensions"
 require_relative "agent_harness/mcp_server"
 require_relative "agent_harness/mcp_config_loader"
 require_relative "agent_harness/mcp_config_translator"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Bart Agapinan
@@ -107,6 +107,7 @@ files:
 - lib/agent_harness/error_taxonomy.rb
 - lib/agent_harness/errors.rb
 - lib/agent_harness/execution_preparation.rb
+- lib/agent_harness/extensions.rb
 - lib/agent_harness/mcp_config_loader.rb
 - lib/agent_harness/mcp_config_translator.rb
 - lib/agent_harness/mcp_server.rb