simple-agent-extension 0.2.1

data/adr/adr-0004-external-agents-and-run-time-agent-selection.md

@@ -0,0 +1,78 @@
+---
+title: "ADR-0004: 外部 Agent の読み込みと実行時の Agent 選択"
+status: "Accepted"
+date: "2026-10-02"
+authors: "T.Watanabe (maintainer)"
+tags: ["architecture", "decision", "extensibility", "security", "agent"]
+supersedes: ""
+superseded_by: ""
+---
+
+# ADR-0004: 外部 Agent の読み込みと実行時の Agent 選択
+
+## Status
+
+Proposed | **Accepted** | Rejected | Superseded | Deprecated
+
+## Context
+
+- 利用者は、組み込み以外の Agent 製品（社内ツールなど）にも対応させたい。
+- Agent class は Ruby コードであり、読み込むことは任意コードの実行を意味する。
+- 一回の実行で対象とする Agent を絞りたい場合がある。これを、source 側の配布宣言（`deploy_to`）と混同したくない。
+- インストールされていない Agent の設定ディレクトリを誤って作りたくない。
+
+## Decision
+
+本 ADR は ADR-0001 の PRI-002（新しい製品には Agent class の追加で対応する）を、本体の外にある Agent class にまで広げる。
+
+### 外部 Agent は信頼されたローカルコードとして明示的に読み込む
+
+- 利用者が指定したディレクトリの直下にある Ruby ファイルだけを読み込む。自動探索、再帰読み込み、リモート取得は行わない。
+- 各ファイルは自己完結し、新しい Agent class を登録しなければならない。他のファイルの Agent class に依存する定義はサポートしない（読み込み順は契約ではない）。読み込み後は組み込みの Agent と区別せずに扱う。
+- 読み込みの失敗、Agent の未登録、Agent 名の重複が起きた場合は、build や deploy を始める前に停止する。
+- sandbox は提供しない。信頼できるコードだけを読み込むのは利用者の責任とし、そのことを文書に明記する。
+
+### 実行時の選択と配布宣言を分ける
+
+- 実行時の Agent 指定は、その回の実行対象を絞るだけとする。artifact の内容や scope は変えない。
+- 未知の Agent 名の扱いは、層によって変える。実行時の指定は利用者のその場の意図なのでエラーにする。`deploy_to` はどの Agent が構成されているか（外部 Agent を含む）に左右される source 側の宣言なので、警告を出して無視する（ADR-0002）。
+
+### 未インストールの Agent には既定で配置しない
+
+- Agent の設定ルートが存在しなければ、その Agent への配置を警告付きでスキップする。明示的に指定したときだけ、ディレクトリを作成して配置する。
+
+## Consequences
+
+### Positive
+
+- **POS-001**: 本体を変更せずに、任意の Agent 製品に対応できる。
+- **POS-002**: 読み込まれるコードが利用者から常に見える。
+- **POS-003**: 構成の誤りを実行前に検出でき、build や deploy の途中結果を残さない。
+- **POS-004**: 一回の実行で対象を絞っても、source の配布宣言の意味は変わらない。
+- **POS-005**: インストールされていない製品のディレクトリを誤って作成しない。
+
+### Negative
+
+- **NEG-001**: 外部 Agent の読み込みは任意コードの実行であり、安全性は利用者の判断に依存する。
+
+## Alternatives Considered
+
+### 外部 Agent の自動探索・再帰読み込み・リモート取得
+
+- **ALT-001**: **Description**: 規約上の場所を自動で探索する、サブディレクトリを再帰的に読み込む、マーケットプレイスやリモートから取得する。
+- **ALT-002**: **Rejection Reason**: どのコードが読み込まれるのかが利用者から見えにくくなり、信頼境界が曖昧になる。
+
+### 外部 Agent の sandbox 実行
+
+- **ALT-003**: **Description**: 外部 Agent class を隔離環境で評価する。
+- **ALT-004**: **Rejection Reason**: Ruby で実用的な sandbox を作るのは難しく、コストに見合わない。信頼モデルを文書化する方針とした。
+
+### インストール判定に extension 用サブディレクトリを用いる
+
+- **ALT-005**: **Description**: 設定ルート配下の `agents/` や `skills/` があるかどうかで判定する。
+- **ALT-006**: **Rejection Reason**: インストール直後の製品はこれらのサブディレクトリをまだ持たないことがあり、誤判定する。
+
+## References
+
+- **REF-001**: ADR-0001、ADR-0002（`deploy_to`）、ADR-0003（artifact scope）
+- **REF-002**: `README.md`「Commands」「External Agent registrations」

data/config/geminabox.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "geminabox"
+
+Geminabox.data = ENV.fetch("GEMINABOX_DATA") do
+  File.expand_path("../tmp/geminabox", __dir__)
+end
+
+run Geminabox::Server

data/exe/simple-agent-extension

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "simple_agent_extension/cli"
+
+exit SimpleAgentExtension::CLI.run(ARGV)

data/lib/simple-agent-extension.rb

@@ -0,0 +1 @@
+require_relative "simple_agent_extension"

data/lib/simple_agent_extension/agent_base.rb

@@ -0,0 +1,119 @@
+module SimpleAgentExtension
+  # An Agent provides metadata translation, artifact core-file placement, and
+  # deployment facts for one type at a time. Compiler and Deployer consume the
+  # Agent interface; they do not call the type-specific methods below directly.
+  #
+  # +extension_type+ selects between "skill" and "agent" through the corresponding
+  # `<type>_metadata`, `<type>_core_file`, `<type>_shared?`, and
+  # `<type>_destination` methods.
+  class AgentBase
+    class MissingMetadataTranslator < Error; end
+
+    include AgentProperty::Skill
+
+    # @param [String, nil] config_dir product-specific configuration directory
+    # @param [String, nil] shared_skill_dir common skill destination
+    def initialize(config_dir: nil, shared_skill_dir: nil)
+      @config_dir = File.expand_path(config_dir) if config_dir
+      @shared_skill_dir = File.expand_path(shared_skill_dir) if shared_skill_dir
+    end
+
+    # @return [String]
+    def config_dir
+      @config_dir || default_config_dir
+    end
+
+    # @return [Boolean] whether the Agent product is installed locally
+    def installed?
+      File.directory?(config_dir)
+    end
+
+    # @return [String]
+    def shared_skill_dir
+      @shared_skill_dir || File.expand_path("~/.agents/skills")
+    end
+
+    # @return [String]
+    def name
+      self.class::NAME
+    end
+
+    # @return [String, nil] one-line summary of the Agent product
+    def description
+      self.class::DESCRIPTION if self.class.const_defined?(:DESCRIPTION)
+    end
+
+    # @return [String, nil] official site of the Agent product
+    def homepage
+      self.class::HOMEPAGE if self.class.const_defined?(:HOMEPAGE)
+    end
+
+    # @param [String, Symbol] type
+    # @param [String, Symbol] field
+    # @return [Boolean] whether this Agent has a translation rule for the field
+    def can_trans_meta?(type:, field:)
+      metadata_translator&.can_translate?(type: type, field: field) || false
+    end
+
+    # @param [String, Symbol] type
+    # @param [String, Symbol] field
+    # @param [Object] value
+    # @return [Hash, nil]
+    # @raise [MissingMetadataTranslator]
+    def trans_meta(type:, field:, value:)
+      translator = metadata_translator
+      raise MissingMetadataTranslator, "#{self.class} has no metadata translator" unless translator
+
+      translator.translate(type: type, field: field, value: value)
+    end
+
+    # @return [AgentProperty::Deployment]
+    def deployment
+      @deployment ||= AgentProperty::Deployment.new(self)
+    end
+
+    # @param [String, Symbol] extension_type
+    # @param [String] extension_name name the extension is deployed under
+    # @param [String] source_file file relative to the source extension directory
+    # @return [String] core file relative to the artifact type directory
+    def artifact_core_file(extension_type:, extension_name:, source_file:)
+      public_send(
+        "#{extension_type}_core_file",
+        extension_name: extension_name,
+        source_file: source_file
+      )
+    end
+
+    def agent_shared?
+      false
+    end
+
+    def agent_destination(scope)
+      return agent_dir if scope == :own
+
+      raise KeyError, "agent has no #{scope} destination"
+    end
+
+    # extension type agent placed in
+    #
+    # @return [String]
+    def agent_dir
+      File.join(config_dir, "agents")
+    end
+
+    def default_config_dir
+      raise NotImplementedError
+    end
+
+    private
+
+    def metadata_translator
+      translator_class = metadata_translator_class
+      translator_class && (@metadata_translator ||= translator_class.new)
+    end
+
+    def metadata_translator_class
+      self.class::MetadataTranslator if self.class.const_defined?(:MetadataTranslator, false)
+    end
+  end
+end

data/lib/simple_agent_extension/agent_directory_loader.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SimpleAgentExtension
+  class InvalidAgentDirectory < Error; end
+  class MissingAgentRegistration < Error; end
+  class UnloadableAgentRegistration < Error; end
+
+  # Loads trusted, explicitly selected Agent registration files for one run.
+  # Discovery is intentionally flat so a directory's registration surface is
+  # visible without implicit recursive loading. Each file must be self-contained:
+  # a registration cannot define an Agent that refers to an Agent defined in a
+  # sibling file, because load order is an implementation detail rather than a
+  # contract. Files are still sorted to keep a run reproducible.
+  class AgentDirectoryLoader
+    def initialize(directories)
+      @directories = Array(directories)
+    end
+
+    def load
+      directories.each do |directory|
+        agent_files(directory).each { |file| load_file(file) }
+      end
+    end
+
+    private
+
+    def directories
+      @directories.map { |directory| canonical_directory(directory) }.uniq
+    end
+
+    def canonical_directory(directory)
+      path = File.expand_path(directory)
+      raise InvalidAgentDirectory, "invalid agent directory: #{path}" unless File.directory?(path)
+
+      path = File.realpath(path)
+      raise InvalidAgentDirectory, "invalid agent directory: #{path}" unless File.readable?(path)
+
+      path
+    end
+
+    def agent_files(directory)
+      Dir.glob(File.join(directory, "*.rb")).sort.map { |file| File.realpath(file) }
+    end
+
+    def load_file(file)
+      known_agent_classes = AgentRegistry.agent_classes
+      require_registration(file)
+
+      return unless (AgentRegistry.agent_classes - known_agent_classes).empty?
+
+      raise MissingAgentRegistration, "#{file}: did not register an Agent"
+    end
+
+    def require_registration(file)
+      require file
+    rescue StandardError, ScriptError => error
+      raise UnloadableAgentRegistration, "#{file}: #{error.class}: #{error.message}"
+    end
+  end
+end

data/lib/simple_agent_extension/agent_property/deployment.rb

@@ -0,0 +1,23 @@
+module SimpleAgentExtension
+  module AgentProperty
+    # Target-specific destinations for already compiled build artifacts.
+    class Deployment
+      def initialize(agent)
+        @agent = agent
+      end
+
+      # @param [String, Symbol] type
+      # @return [Boolean]
+      def shared?(type)
+        @agent.public_send("#{type}_shared?")
+      end
+
+      # @param [String, Symbol] type
+      # @param [Symbol] scope
+      # @return [String]
+      def destination(type, scope)
+        @agent.public_send("#{type}_destination", scope)
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/agent_property/metadata_translator.rb

@@ -0,0 +1,55 @@
+module SimpleAgentExtension
+  module AgentProperty
+    # Converts one source metadata field into Agent metadata fragments. Callers
+    # retain ownership of field traversal and fragment composition.
+    class MetadataTranslator
+      class UnknownTypeAndFieldCombination < Error; end
+
+      # Class methods for defining translations
+      class << self
+        # @param [String, Symbol] type ( `skill' or `agent' or ... )
+        # @param [String, Symbol] field ( metadata's field name )
+        # @param [#call] transform
+        # @yieldparam value [Object] value of the declared source metadata field
+        # @yieldreturn [Hash, nil] Agent metadata fragment collection, or field omission
+        def define_translation(type:, field:, &transform)
+          raise ArgumentError, "define_translation requires a block" unless transform
+
+          translations[[type.to_sym, field.to_s]] = transform
+        end
+
+        # @return [Hash{[String, String] => #call}]
+        def translations
+          @translations ||= {}
+        end
+      end
+
+      # @return [Hash{[String, String] => #call}]
+      def translations
+        self.class.translations
+      end
+
+      # @param [String] type
+      # @param [String] field
+      # @return [Boolean] whether a translation rule is registered
+      def can_translate?(type:, field:)
+        self.class.translations.key?([type.to_sym, field.to_s])
+      end
+
+      # translation entrypoint
+      #
+      # @param [String, Symbol] type
+      # @param [String, Symbol] field
+      # @param [Object] value
+      # @return [Hash, nil] Agent metadata fragment collection, or omission
+      # @raise [UnknownTypeAndFieldCombination] when no translation is registered for type and field
+      def translate(type:, field:, value:)
+        transform = self.class.translations.fetch([type.to_sym, field.to_s]) {
+          raise UnknownTypeAndFieldCombination.new("Unknown combination of type: `#{type}' and field: `#{field}'")
+        }
+
+        transform.call(value)
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/agent_property/skill.rb

@@ -0,0 +1,29 @@
+module SimpleAgentExtension
+  module AgentProperty
+    # The area several targets read, and the shared shape of a skill's
+    # metadata.
+    #
+    # Skills live in the shared area until a target needs something of its
+    # own lowered into them; at that point compile sends them to +own+.
+    module Skill
+      def skill_shared?
+        true
+      end
+
+      def skill_destination(scope)
+        case scope
+        when :shared then shared_skill_dir
+        when :own then File.join(config_dir, "skills")
+        else raise KeyError, "skill has no #{scope} destination"
+        end
+      end
+
+      # @param [String] extension_name
+      # @param [String] source_file
+      # @return [String] core file relative to the artifact type directory
+      def skill_core_file(extension_name:, source_file:)
+        File.join(extension_name, source_file)
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/agent_property.rb

@@ -0,0 +1,8 @@
+module SimpleAgentExtension
+  module AgentProperty
+  end
+end
+
+require_relative "agent_property/metadata_translator"
+require_relative "agent_property/skill"
+require_relative "agent_property/deployment"

data/lib/simple_agent_extension/agent_registry.rb

@@ -0,0 +1,99 @@
+module SimpleAgentExtension
+  class DuplicatedAgentName < Error; end
+  class DuplicatedAgentConfigurationName < Error; end
+  class UnknownAgentName < Error; end
+
+  # A configured set of deployment Agent instances for one run.
+  #
+  # Agents remains the namespace for product classes. This registry owns the
+  # runtime concerns that need an instance collection: lookup by name,
+  # membership, and duplicate-name rejection.
+  class AgentRegistry
+    # @return [AgentRegistry] all known Agents at their default destinations
+    def self.default
+      new(agent_classes.map(&:new))
+    end
+
+    # Applies destination overrides without modifying the default registry or
+    # any other registry. Missing entries retain their Agent defaults; entries
+    # do not select which Agents are present.
+    #
+    # @param [Hash{String, Symbol => Hash}] overrides per-Agent initializer options
+    # @return [AgentRegistry]
+    def self.configure(overrides = {})
+      options = options_by_agent(overrides)
+      defaults = default
+      unknown = options.keys - defaults.all.map(&:name)
+      raise UnknownAgentName, "unknown agent: #{unknown.first}" unless unknown.empty?
+
+      new(defaults.all.map { |agent|
+        agent.class.new(**options.fetch(agent.name, {}))
+      })
+    end
+
+    # @return [Array<Class>] concrete Agent classes
+    def self.agent_classes
+      Agents.constants(false)
+        .map { |const| Agents.const_get(const) }
+        .select { |klass| klass.is_a?(Class) && klass < AgentBase }
+        .sort_by(&:name)
+    end
+
+    # Converts Agent-name keys and Agent initializer option keys to their
+    # canonical String and Symbol forms, as below.
+    #
+    # ```
+    # name[String] => {
+    #   key[Symbol] => val,
+    #   key[Symbol] => val
+    # }
+    # ```
+    #
+    # @param [Hash{String, Symbol => Hash}] overrides per-Agent destination options
+    # @return [Hash{String => Hash{Symbol => Object}}]
+    # @raise [ArgumentError] when names are duplicated after normalization
+    def self.options_by_agent(overrides)
+      overrides.each_with_object({}) do |(name, agent_options), options|
+        key = name.to_s
+        raise DuplicatedAgentConfigurationName, "duplicate agent configuration: #{key}" if options.key?(key)
+
+        options[key] = agent_options.transform_keys(&:to_sym)
+      end
+    end
+
+    # @param [Array<AgentBase>] agents configured instances for one run
+    # @raise [ArgumentError] when names are duplicated
+    def initialize(agents)
+      @agents = agents.dup.freeze
+      @by_name = @agents.each_with_object({}) do |agent, index|
+        raise DuplicatedAgentName, "duplicate agent: #{agent.name}" if index.key?(agent.name)
+
+        index[agent.name] = agent
+      end.freeze
+    end
+
+    # @yield [AgentBase]
+    # @return [Enumerator]
+    def each(&block)
+      @agents.each(&block)
+    end
+
+    # @return [Array<AgentBase>]
+    def all
+      @agents
+    end
+
+    # @param [String, Symbol] name
+    # @return [AgentBase]
+    # @raise [KeyError] when no configured instance has this name
+    def fetch(name)
+      @by_name.fetch(name.to_s) { raise UnknownAgentName, "unknown agent: #{name}" }
+    end
+
+    # @param [String, Symbol] name
+    # @return [Boolean]
+    def include?(name)
+      @by_name.key?(name.to_s)
+    end
+  end
+end

data/lib/simple_agent_extension/agents/claude_code.rb

@@ -0,0 +1,62 @@
+module SimpleAgentExtension
+  module Agents
+    class ClaudeCode < AgentBase
+      NAME = "claude".freeze
+      DESCRIPTION = "Claude Code, Anthropic's terminal coding agent".freeze
+      HOMEPAGE = "https://www.anthropic.com/claude-code".freeze
+
+      class MetadataTranslator < ::SimpleAgentExtension::AgentProperty::MetadataTranslator
+        # Source tool names that differ from Claude Code's exact tool names.
+        # Names not listed here pass through unchanged.
+        TOOL_NAMES = {
+          "read" => "Read",
+          "edit" => "Edit",
+          "write" => "Write",
+          "bash" => "Bash",
+          "glob" => "Glob",
+          "grep" => "Grep",
+          "webfetch" => "WebFetch",
+          "websearch" => "WebSearch",
+          "task" => "Agent",
+          "todowrite" => "TodoWrite"
+        }.freeze
+
+        # A subagent's `tools` limits which tools it has without pre-approving
+        # them, so `allow` and `ask` become indistinguishable here.
+        define_translation type: :agent, field: "permissions" do |permissions|
+          tool_fields(permissions, "tools" => %w[allow ask], "disallowedTools" => %w[deny])
+        end
+
+        define_translation type: :skill, field: "permissions" do |permissions|
+          tool_fields(permissions, "allowed-tools" => %w[allow], "disallowed-tools" => %w[deny])
+        end
+
+        # @param [Hash{String => String}] permissions tool name to action
+        # @param [Hash{String => Array<String>}] actions_by_field output field to the actions it lists
+        # @return [Hash{String => String}] comma-separated tool names; empty fields are omitted
+        def self.tool_fields(permissions, actions_by_field)
+          actions_by_field.each_with_object({}) do |(field, actions), fields|
+            tools = permissions.filter_map { |tool, action| TOOL_NAMES.fetch(tool, tool) if actions.include?(action) }
+            fields[field] = tools.join(", ") unless tools.empty?
+          end
+        end
+      end
+
+      def skill_shared?
+        false
+      end
+
+      # @return [String]
+      def default_config_dir
+        File.expand_path("~/.claude")
+      end
+
+      # @param [String] extension_name
+      # @param [String] source_file
+      # @return [String] core file relative to the artifact type directory
+      def agent_core_file(extension_name:, source_file: _source_file)
+        "#{extension_name}.md"
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/agents/copilot.rb

@@ -0,0 +1,30 @@
+module SimpleAgentExtension
+  module Agents
+    class Copilot < AgentBase
+      NAME = "copilot".freeze
+      DESCRIPTION = "GitHub Copilot CLI".freeze
+      HOMEPAGE = "https://github.com/features/copilot/cli".freeze
+
+      class MetadataTranslator < ::SimpleAgentExtension::AgentProperty::MetadataTranslator
+        define_translation type: :skill, field: "permissions" do |permissions|
+          {"tools" => permissions.filter_map { |tool, action| tool if action == "allow" }}
+        end
+
+        define_translation type: :agent, field: "permissions" do |permissions|
+          {"tools" => permissions.filter_map { |tool, action| tool if action == "allow" }}
+        end
+      end
+
+      def default_config_dir
+        File.expand_path("~/.copilot")
+      end
+
+      # @param [String] extension_name
+      # @param [String] source_file
+      # @return [String] core file relative to the artifact type directory
+      def agent_core_file(extension_name:, source_file: _source_file)
+        "#{extension_name}.agent.md"
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/agents/opencode.rb

@@ -0,0 +1,35 @@
+module SimpleAgentExtension
+  module Agents
+    class OpenCode < AgentBase
+      NAME = "opencode".freeze
+      DESCRIPTION = "OpenCode, an open source terminal coding agent".freeze
+      HOMEPAGE = "https://opencode.ai".freeze
+
+      class MetadataTranslator < ::SimpleAgentExtension::AgentProperty::MetadataTranslator
+        define_translation type: :skill, field: "permissions" do |permissions|
+          {"permission" => permissions}
+        end
+
+        define_translation type: :agent, field: "name" do |_name|
+          nil
+        end
+
+        define_translation type: :agent, field: "permissions" do |permissions|
+          {"permission" => permissions}
+        end
+      end
+
+      # @return [String]
+      def default_config_dir
+        File.join(File.expand_path("~/.config"), "opencode")
+      end
+
+      # @param [String] extension_name
+      # @param [String] source_file
+      # @return [String] core file relative to the artifact type directory
+      def agent_core_file(extension_name:, source_file: _source_file)
+        "#{extension_name}.md"
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/agents.rb

@@ -0,0 +1,11 @@
+module SimpleAgentExtension
+  # Concrete coding-agent product classes.
+  module Agents
+  end
+end
+
+require_relative "agent_property"
+require_relative "agent_base"
+require_relative "agents/claude_code"
+require_relative "agents/copilot"
+require_relative "agents/opencode"