aia 2.0.0.0.pre.alpha → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. checksums.yaml +4 -4
  2. data/.version +1 -1
  3. data/CHANGELOG.md +151 -228
  4. data/README.md +42 -19
  5. data/bin/aia +8 -3
  6. data/lib/aia/aia_completion.bash +2 -3
  7. data/lib/aia/aia_completion.fish +6 -5
  8. data/lib/aia/aia_completion.zsh +2 -3
  9. data/lib/aia/chat_loop.rb +24 -66
  10. data/lib/aia/config/cli_parser.rb +164 -123
  11. data/lib/aia/config/defaults.yml +12 -39
  12. data/lib/aia/config/mcp_parser.rb +42 -40
  13. data/lib/aia/config/model_spec.rb +8 -14
  14. data/lib/aia/config/validator.rb +144 -156
  15. data/lib/aia/config/value_caster.rb +76 -0
  16. data/lib/aia/config.rb +72 -54
  17. data/lib/aia/content_extractor.rb +2 -0
  18. data/lib/aia/cost_calculator.rb +1 -0
  19. data/lib/aia/crew.rb +29 -19
  20. data/lib/aia/debate_handler.rb +45 -20
  21. data/lib/aia/delegate_handler.rb +7 -3
  22. data/lib/aia/directive.rb +10 -8
  23. data/lib/aia/directives/configuration_directives.rb +164 -109
  24. data/lib/aia/directives/context_directives.rb +55 -40
  25. data/lib/aia/directives/execution_directives.rb +25 -25
  26. data/lib/aia/directives/model_directives.rb +112 -195
  27. data/lib/aia/directives/trakflow_directives.rb +27 -9
  28. data/lib/aia/directives/utility_directives.rb +86 -87
  29. data/lib/aia/directives/web_and_file_directives.rb +83 -63
  30. data/lib/aia/fact_asserter.rb +3 -3
  31. data/lib/aia/history_transfer.rb +64 -24
  32. data/lib/aia/layered_orchestrator.rb +66 -43
  33. data/lib/aia/logger.rb +27 -62
  34. data/lib/aia/mcp_config_normalizer.rb +27 -14
  35. data/lib/aia/mcp_connection_manager.rb +193 -186
  36. data/lib/aia/mcp_discovery.rb +43 -15
  37. data/lib/aia/mcp_grouper.rb +2 -1
  38. data/lib/aia/mcp_server_config.rb +48 -0
  39. data/lib/aia/mcp_utility.rb +28 -20
  40. data/lib/aia/mention_router.rb +22 -52
  41. data/lib/aia/modality_query.rb +36 -0
  42. data/lib/aia/model_alias_registry.rb +11 -11
  43. data/lib/aia/model_registry.rb +75 -0
  44. data/lib/aia/network_builder.rb +17 -11
  45. data/lib/aia/network_memory_manager.rb +6 -6
  46. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  47. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  48. data/lib/aia/pipeline_orchestrator.rb +88 -45
  49. data/lib/aia/plugin_monitor.rb +9 -6
  50. data/lib/aia/prompt_decomposer.rb +6 -4
  51. data/lib/aia/prompt_handler.rb +90 -69
  52. data/lib/aia/provider_registry.rb +105 -0
  53. data/lib/aia/robot_builder.rb +1 -1
  54. data/lib/aia/robot_factory.rb +77 -69
  55. data/lib/aia/robot_namer.rb +2 -8
  56. data/lib/aia/robot_sync.rb +79 -0
  57. data/lib/aia/role_catalog.rb +89 -0
  58. data/lib/aia/session.rb +32 -14
  59. data/lib/aia/session_tracker.rb +39 -41
  60. data/lib/aia/similarity_scorer.rb +5 -3
  61. data/lib/aia/skill_utils.rb +60 -19
  62. data/lib/aia/spawn_handler.rb +16 -4
  63. data/lib/aia/spawn_spec_parser.rb +6 -7
  64. data/lib/aia/special_mode_handler.rb +80 -57
  65. data/lib/aia/speech.rb +103 -0
  66. data/lib/aia/startup_coordinator.rb +17 -91
  67. data/lib/aia/streaming_runner.rb +16 -5
  68. data/lib/aia/system_prompt_assembler.rb +20 -15
  69. data/lib/aia/task_board.rb +60 -0
  70. data/lib/aia/task_coordinator.rb +10 -5
  71. data/lib/aia/timing.rb +15 -0
  72. data/lib/aia/tool_approver.rb +205 -0
  73. data/lib/aia/tool_filter.rb +1 -9
  74. data/lib/aia/tool_filter_strategy.rb +39 -25
  75. data/lib/aia/tool_introspection.rb +25 -0
  76. data/lib/aia/tool_loader.rb +71 -31
  77. data/lib/aia/tool_utility.rb +6 -5
  78. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  79. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  80. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  81. data/lib/aia/tools/task_board_tool.rb +17 -16
  82. data/lib/aia/trakflow_bridge.rb +19 -11
  83. data/lib/aia/turn_state.rb +32 -8
  84. data/lib/aia/ui_presenter.rb +83 -59
  85. data/lib/aia/utility.rb +8 -24
  86. data/lib/aia/variable_input_collector.rb +1 -3
  87. data/lib/aia/verification_network.rb +10 -12
  88. data/lib/aia.rb +49 -8
  89. metadata +27 -162
  90. data/.better-commits.json +0 -150
  91. data/.config/tocer/configuration.yml +0 -6
  92. data/.envrc +0 -15
  93. data/.loki +0 -231
  94. data/.quality/flay_baseline.txt +0 -1
  95. data/.quality/flog_baseline.txt +0 -29
  96. data/.quality/reek_baseline.txt +0 -80
  97. data/.rubocop.yml +0 -116
  98. data/COMMITS.md +0 -196
  99. data/IMPLEMENTATION_PLAN.md +0 -506
  100. data/Rakefile +0 -160
  101. data/architecture_review.md +0 -314
  102. data/docs/AGENTS.md +0 -40
  103. data/docs/advanced-prompting.md +0 -814
  104. data/docs/assets/images/aia.png +0 -0
  105. data/docs/cli-reference.md +0 -1241
  106. data/docs/configuration.md +0 -747
  107. data/docs/contributing.md +0 -386
  108. data/docs/directives-reference.md +0 -1145
  109. data/docs/examples/index.md +0 -277
  110. data/docs/examples/mcp/index.md +0 -475
  111. data/docs/examples/prompts/analysis/index.md +0 -78
  112. data/docs/examples/prompts/automation/index.md +0 -109
  113. data/docs/examples/prompts/development/index.md +0 -125
  114. data/docs/examples/prompts/index.md +0 -333
  115. data/docs/examples/prompts/learning/index.md +0 -127
  116. data/docs/examples/prompts/writing/index.md +0 -62
  117. data/docs/examples/tools/index.md +0 -282
  118. data/docs/faq.md +0 -578
  119. data/docs/guides/available-models.md +0 -366
  120. data/docs/guides/basic-usage.md +0 -478
  121. data/docs/guides/chat.md +0 -680
  122. data/docs/guides/crew.md +0 -239
  123. data/docs/guides/executable-prompts.md +0 -331
  124. data/docs/guides/first-prompt.md +0 -454
  125. data/docs/guides/getting-started.md +0 -455
  126. data/docs/guides/image-generation.md +0 -507
  127. data/docs/guides/index.md +0 -48
  128. data/docs/guides/local-models.md +0 -306
  129. data/docs/guides/migrate-prompts.md +0 -335
  130. data/docs/guides/models.md +0 -1017
  131. data/docs/guides/shared-tools.md +0 -254
  132. data/docs/guides/tools.md +0 -831
  133. data/docs/index.md +0 -259
  134. data/docs/installation.md +0 -274
  135. data/docs/mcp-integration.md +0 -603
  136. data/docs/prompt_management.md +0 -665
  137. data/docs/security.md +0 -674
  138. data/docs/special_projects_guide.md +0 -386
  139. data/docs/tools-and-mcp-examples.md +0 -1211
  140. data/docs/workflows-and-pipelines.md +0 -636
  141. data/examples/.gitignore +0 -2
  142. data/examples/00_setup_aia.sh +0 -111
  143. data/examples/01_basic_usage.sh +0 -23
  144. data/examples/02_frontmatter.sh +0 -33
  145. data/examples/03_shell_integration.sh +0 -55
  146. data/examples/04_erb_templating.sh +0 -56
  147. data/examples/05_shell_then_erb.sh +0 -38
  148. data/examples/06_prompt_chaining.sh +0 -59
  149. data/examples/07_pipeline.sh +0 -46
  150. data/examples/08_context_files.sh +0 -43
  151. data/examples/09_roles.sh +0 -67
  152. data/examples/10_stdin_piping.sh +0 -49
  153. data/examples/11_multi_model.sh +0 -65
  154. data/examples/12_token_usage.sh +0 -52
  155. data/examples/13_cost_tracking.sh +0 -68
  156. data/examples/14_output_file.sh +0 -91
  157. data/examples/15_parameters.sh +0 -68
  158. data/examples/16_directives.sh +0 -113
  159. data/examples/17_require_and_conditionals.sh +0 -68
  160. data/examples/18_tools.sh +0 -61
  161. data/examples/19_local_tools.sh +0 -34
  162. data/examples/20_mcp_servers.sh +0 -102
  163. data/examples/21_executable_prompts.sh +0 -78
  164. data/examples/22_chat_mode.sh +0 -217
  165. data/examples/23_verify.sh +0 -139
  166. data/examples/24_decompose.sh +0 -139
  167. data/examples/25_spawn.sh +0 -139
  168. data/examples/26_debate.sh +0 -97
  169. data/examples/27_mention_routing.sh +0 -157
  170. data/examples/28_model_switching.sh +0 -106
  171. data/examples/29_agent_harness.sh +0 -177
  172. data/examples/README.md +0 -321
  173. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  174. data/examples/aia_config.yml +0 -22
  175. data/examples/aia_config_orchestrator.yml +0 -45
  176. data/examples/aia_config_with_mcp.yml +0 -21
  177. data/examples/common.sh +0 -39
  178. data/examples/context/project_goals.md +0 -6
  179. data/examples/context/tech_stack.md +0 -7
  180. data/examples/directives/timestamp_directive.rb +0 -22
  181. data/examples/mcp/filesystem.json +0 -9
  182. data/examples/prompts_dir/analyze.md +0 -2
  183. data/examples/prompts_dir/brainstorm.md +0 -2
  184. data/examples/prompts_dir/conditional.md +0 -17
  185. data/examples/prompts_dir/creative.md +0 -4
  186. data/examples/prompts_dir/erbinfo.md +0 -5
  187. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  188. data/examples/prompts_dir/evaluate.md +0 -2
  189. data/examples/prompts_dir/explain_joke.md +0 -1
  190. data/examples/prompts_dir/explain_recursion.md +0 -1
  191. data/examples/prompts_dir/fun_fact +0 -3
  192. data/examples/prompts_dir/greeting.md +0 -8
  193. data/examples/prompts_dir/greeting_required.md +0 -7
  194. data/examples/prompts_dir/hello.md +0 -1
  195. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  196. data/examples/prompts_dir/limerick.md +0 -1
  197. data/examples/prompts_dir/list_with_mcp.md +0 -3
  198. data/examples/prompts_dir/pick_best.md +0 -2
  199. data/examples/prompts_dir/project_summary +0 -12
  200. data/examples/prompts_dir/quiz_with_include.md +0 -6
  201. data/examples/prompts_dir/require_demo.md +0 -5
  202. data/examples/prompts_dir/roles/formal.md +0 -3
  203. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  204. data/examples/prompts_dir/roles/pirate.md +0 -3
  205. data/examples/prompts_dir/shell_then_erb.md +0 -6
  206. data/examples/prompts_dir/sort_compare.md +0 -2
  207. data/examples/prompts_dir/summarize_context.md +0 -2
  208. data/examples/prompts_dir/sysinfo.md +0 -5
  209. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  210. data/examples/prompts_dir/tagline.md +0 -1
  211. data/examples/prompts_dir/tell_joke.md +0 -1
  212. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  213. data/examples/prompts_dir/use_local_tool.md +0 -8
  214. data/examples/prompts_dir/use_tools.md +0 -8
  215. data/examples/prompts_dir/weather.md +0 -2
  216. data/examples/prompts_dir/whats_new.md +0 -2
  217. data/examples/prompts_dir/with_timestamp.md +0 -5
  218. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  219. data/examples/rules/01_classify_ruby.rb +0 -16
  220. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  221. data/examples/rules/03_gate_prompt_length.rb +0 -19
  222. data/examples/rules/04_tool_selection.rb +0 -41
  223. data/examples/rules/README.md +0 -30
  224. data/examples/run_all.sh +0 -294
  225. data/examples/tools/word_count_tool.rb +0 -30
  226. data/lib/AGENTS.md +0 -57
  227. data/lib/aia/model_switch_handler.rb +0 -100
  228. data/mcp_servers/README.md +0 -110
  229. data/mcp_servers/apple-mcp.json +0 -8
  230. data/mcp_servers/filesystem.json +0 -9
  231. data/mcp_servers/mcp_server_chart.json +0 -11
  232. data/mcp_servers/playwright_one.json +0 -8
  233. data/mcp_servers/playwright_server_definition.json +0 -9
  234. data/mcp_servers/playwright_two.json +0 -8
  235. data/mcp_servers/tavily_mcp_server.json +0 -8
  236. data/mkdocs.yml +0 -169
@@ -11,7 +11,6 @@
11
11
  # transport: { type: "stdio", command: "npx", args: [...], env: {...} },
12
12
  # timeout: 8000,
13
13
  # topics: ["routing"], # AIA routing metadata (optional)
14
- # independent: false, # AIA concurrency metadata (optional)
15
14
  # group: "services" # AIA grouping metadata (optional)
16
15
  # }
17
16
  #
@@ -39,12 +38,19 @@ require 'json'
39
38
 
40
39
  module AIA
41
40
  module McpParser
41
+ # Keys that describe how to reach the server; they go into :transport.
42
+ TRANSPORT_KEYS = %w[type command args env url headers bearer_token oauth cwd directory].freeze
43
+
44
+ # Server settings robot_lab understands, carried through as written.
45
+ SERVER_KEYS = %w[prefix only except requires_approval description].freeze
46
+
42
47
  class << self
43
48
  # Parse MCP server configuration files and return array of server configs
44
49
  # in robot_lab's nested transport format.
45
50
  #
46
51
  # @param file_paths [Array<String>] paths to JSON configuration files
47
52
  # @return [Array<Hash>] array of server configurations with nested transport
53
+ # :reek:TooManyStatements -- per-file loop with warn-and-continue handling for missing files, bad JSON, and read errors
48
54
  def parse_files(file_paths)
49
55
  return [] if file_paths.nil? || file_paths.empty?
50
56
 
@@ -92,52 +98,48 @@ module AIA
92
98
  # @param mcp_servers [Hash] the mcpServers hash from JSON
93
99
  # @return [Array<Hash>] array of server configurations
94
100
  def convert_mcp_servers_format(mcp_servers)
95
- mcp_servers.map do |name, config|
96
- transport = { type: config['type'] || 'stdio' }
97
- transport[:command] = config['command'] if config['command']
98
- transport[:args] = Array(config['args']) if config['args']
99
- transport[:env] = config['env'] if config['env']
100
- transport[:url] = config['url'] if config['url']
101
- transport[:headers] = config['headers'] if config['headers']
102
-
103
- server = { name: name, transport: transport }
104
- server[:timeout] = config['timeout'].to_i if config['timeout']
105
-
106
- # Preserve routing metadata for KBS/AIA
107
- server[:topics] = Array(config['topics']) if config['topics']
108
- server[:independent] = config['independent'] unless config['independent'].nil?
109
- server[:group] = config['group'] if config['group']
110
-
111
- server
101
+ mcp_servers.map { |name, config| build_server(name, config) }
102
+ end
103
+
104
+ # One server in robot_lab's format. Both JSON forms accept the same keys.
105
+ def build_server(name, config)
106
+ server = { name: name, transport: build_transport(config) }
107
+ server[:timeout] = config['timeout'].to_i if config['timeout']
108
+ SERVER_KEYS.each { |key| server[key.to_sym] = config[key] if config.key?(key) }
109
+ server.merge!(routing_metadata(config))
110
+ end
111
+
112
+ # The transport hash. With no "type", a url means Streamable HTTP and
113
+ # anything else stdio. A "command" given as an array holds the command
114
+ # followed by its arguments.
115
+ def build_transport(config)
116
+ transport = config.slice(*TRANSPORT_KEYS).transform_keys(&:to_sym)
117
+ command = transport[:command]
118
+ if command.is_a?(Array)
119
+ transport[:command] = command.first
120
+ transport[:args] = Array(command[1..]) + Array(transport[:args])
112
121
  end
122
+ transport[:args] = Array(transport[:args]) if transport.key?(:args)
123
+ transport[:type] ||= transport[:url] && !transport[:command] ? 'streamable-http' : 'stdio'
124
+ transport
113
125
  end
114
126
 
115
- # Convert simple format to robot_lab nested transport format
127
+ # Routing metadata preserved for KBS/AIA
128
+ def routing_metadata(config)
129
+ meta = {}
130
+ meta[:topics] = Array(config['topics']) if config['topics']
131
+ meta[:group] = config['group'] if config['group']
132
+ meta
133
+ end
134
+
135
+ # Convert simple format to robot_lab nested transport format. The
136
+ # server is named after the file ("filesystem.json" -> "filesystem").
116
137
  #
117
- # @param parsed [Hash] parsed JSON with type and command
138
+ # @param parsed [Hash] one server's settings
118
139
  # @param file_path [String] file path for deriving server name
119
140
  # @return [Array<Hash>] array with single server configuration
120
141
  def convert_simple_format(parsed, file_path)
121
- # Derive name from filename (e.g., "filesystem.json" -> "filesystem")
122
- name = File.basename(file_path, '.*')
123
-
124
- transport = { type: parsed['type'] || 'stdio' }
125
-
126
- if parsed['command'].is_a?(Array)
127
- # Command is an array: first element is command, rest are args
128
- transport[:command] = parsed['command'].first
129
- transport[:args] = parsed['command'][1..] || []
130
- elsif parsed['command']
131
- transport[:command] = parsed['command']
132
- transport[:args] = parsed['args'] || []
133
- end
134
-
135
- transport[:env] = parsed['env'] if parsed['env']
136
-
137
- server = { name: name, transport: transport }
138
- server[:timeout] = parsed['timeout'].to_i if parsed['timeout']
139
-
140
- [server]
142
+ [build_server(File.basename(file_path, '.*'), parsed)]
141
143
  end
142
144
  end
143
145
  end
@@ -15,14 +15,6 @@ module AIA
15
15
  class ModelSpec
16
16
  attr_accessor :name, :role, :instance, :internal_id, :provider
17
17
 
18
- # Provider prefixes that map to RubyLLM provider slugs.
19
- # 'lms' is stored as-is; RobotFactory maps it to the openai provider
20
- # with a custom API base so it doesn't conflict with real OpenAI models.
21
- PROVIDER_ALIASES = {
22
- 'ollama' => 'ollama',
23
- 'lms' => 'lms'
24
- }.freeze
25
-
26
18
  def initialize(hash = {})
27
19
  hash = hash.transform_keys(&:to_sym) if hash.respond_to?(:transform_keys)
28
20
 
@@ -32,7 +24,7 @@ module AIA
32
24
  @internal_id = hash[:internal_id] || @name
33
25
  @provider = hash[:provider]
34
26
 
35
- # Extract provider from name if prefixed (e.g., "ollama/llama3" or "lms/my-model")
27
+ # Extract provider from name if prefixed (e.g., "<provider>/<model-id>")
36
28
  extract_provider_from_name! unless @provider
37
29
  end
38
30
 
@@ -84,15 +76,17 @@ module AIA
84
76
 
85
77
  private
86
78
 
87
- # Extract provider prefix from model name.
88
- # "ollama/llama3:latest" => provider: "ollama", name: "llama3:latest"
89
- # "lms/my-model" => provider: "openai", name: "my-model"
79
+ # Extract a provider prefix from the model name. The prefix is a provider
80
+ # exactly when RubyLLM knows it (registered already, or loadable as a
81
+ # conventional ruby_llm-providers-<prefix> gem) — no provider names are
82
+ # hardcoded here. Names whose first segment is not a provider (registry
83
+ # ids like "meta-llama/llama-4-maverick") pass through untouched.
90
84
  def extract_provider_from_name!
91
85
  return unless @name&.include?('/')
92
86
 
93
87
  prefix, rest = @name.split('/', 2)
94
- return unless PROVIDER_ALIASES.key?(prefix)
95
- @provider = PROVIDER_ALIASES[prefix]
88
+ return unless ProviderRegistry.available?(prefix)
89
+ @provider = prefix
96
90
  @name = rest
97
91
  end
98
92
  end
@@ -1,7 +1,10 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require 'timeout'
4
+ require 'did_you_mean'
3
5
  require 'word_wrapper'
4
6
  require_relative '../skill_utils'
7
+ require_relative '../role_catalog'
5
8
 
6
9
  # lib/aia/config/validator.rb
7
10
  #
@@ -16,6 +19,7 @@ module AIA
16
19
  #
17
20
  # @param config [AIA::Config] the configuration to validate
18
21
  # @return [AIA::Config] the validated configuration
22
+ # :reek:TooManyStatements -- top-level validation pipeline: one named step per line, executed in fixed order
19
23
  def tailor(config)
20
24
  remaining_args = config.remaining_args&.dup || []
21
25
  config.remaining_args = nil
@@ -33,12 +37,13 @@ module AIA
33
37
  handle_executable_prompt(config)
34
38
  handle_stdin_as_prompt(config)
35
39
  return :early_exit if handle_early_exits(config) == :early_exit
36
- validate_required_prompt_id(config)
40
+ adopt_pipeline_head(config)
37
41
  process_role_configuration(config)
42
+ validate_model_roles(config)
43
+ validate_required_prompt_id(config)
38
44
  validate_plugins_dir(config)
39
45
  handle_fuzzy_search_prompt_id(config)
40
46
  normalize_boolean_flags(config)
41
- validate_final_prompt_requirements(config)
42
47
  prepare_pipeline(config)
43
48
  validate_pipeline_prompts(config)
44
49
 
@@ -50,6 +55,7 @@ module AIA
50
55
  return :early_exit if handle_mcp_list(config) == :early_exit
51
56
  return :early_exit if handle_list_tools(config) == :early_exit
52
57
  return :early_exit if handle_list_skills(config) == :early_exit
58
+ return :early_exit if handle_list_roles(config) == :early_exit
53
59
  :early_exit if handle_completion_script(config) == :early_exit
54
60
  end
55
61
 
@@ -92,6 +98,7 @@ module AIA
92
98
  "Did you mean: #{suggestions}?\n" \
93
99
  "Flags require a dash prefix (e.g., -B not _B)."
94
100
  end
101
+ raise AIA::ConfigurationError, missing_prompt_message(config, bad_files) if missing_prompt_id?(config, remaining_args, bad_files)
95
102
  raise AIA::ConfigurationError, "The following files do not exist: #{bad_files.join(', ')}"
96
103
  end
97
104
 
@@ -99,62 +106,100 @@ module AIA
99
106
  config.context_files += remaining_args
100
107
  end
101
108
 
109
+ # The first argument looks like a prompt ID (no extension) but names
110
+ # neither a prompt nor a file.
111
+ def missing_prompt_id?(config, remaining_args, bad_files)
112
+ word = remaining_args.first
113
+ config.prompt_id.nil? && bad_files.first == word && File.extname(word).empty?
114
+ end
115
+
116
+ def missing_prompt_message(config, bad_files)
117
+ word, *others = bad_files
118
+ dir = config.prompts.dir
119
+ message = "No prompt named '#{word}' in #{dir} (and no file by that name)."
120
+ suggestions = prompt_suggestions(word, dir, config.prompts.extname)
121
+ message += "\nDid you mean: #{suggestions.join(', ')}?" if suggestions.any?
122
+ message += "\nThe following files do not exist: #{others.join(', ')}" if others.any?
123
+ message
124
+ end
125
+
126
+ # Prompt IDs under +dir+ that are close spellings of +word+.
127
+ def prompt_suggestions(word, dir, extname)
128
+ return [] unless dir && Dir.exist?(dir)
129
+
130
+ ids = Dir.glob("**/*#{extname}", base: dir).map { it.delete_suffix(extname) }
131
+ DidYouMean::SpellChecker.new(dictionary: ids).correct(word).first(3)
132
+ end
133
+
102
134
  def handle_executable_prompt(config)
103
135
  return unless config.prompt_id.nil?
104
- return unless config.context_files && !config.context_files.empty?
105
136
 
106
- candidate = config.context_files.first
137
+ files = config.context_files
138
+ return unless files && !files.empty?
139
+
140
+ candidate = files.first
107
141
  return unless File.exist?(candidate) && File.readable?(candidate)
108
142
 
109
143
  first_line = File.open(candidate, &:readline).strip rescue nil
110
144
  return unless first_line&.start_with?('#!')
111
145
 
112
- config.context_files.shift
146
+ files.shift
113
147
  config.executable_prompt_content = File.read(candidate).lines[1..].join
114
148
  config.prompt_id = '__EXECUTABLE_PROMPT__'
115
149
  end
116
150
 
117
151
  def handle_stdin_as_prompt(config)
118
152
  return unless config.prompt_id.nil?
119
- return unless config.stdin_content && !config.stdin_content.strip.empty?
120
-
121
153
  content = config.stdin_content
154
+ return unless content && !content.strip.empty?
122
155
 
123
- if content.lines.first&.strip&.start_with?('#!')
124
- content = content.lines[1..].join
125
- end
126
-
127
- config.executable_prompt_content = content
156
+ config.executable_prompt_content = strip_shebang(content)
128
157
  config.stdin_content = nil
129
158
  config.prompt_id = '__EXECUTABLE_PROMPT__'
130
159
  end
131
160
 
161
+ # Piped text arrives with a leading newline (see process_stdin_content).
162
+ # Drop it, and a "#!" line if the text starts with one, so the front
163
+ # matter that follows is recognized.
164
+ def strip_shebang(content)
165
+ text = content.delete_prefix("\n")
166
+ text.start_with?('#!') ? text.lines[1..].join : text
167
+ end
168
+
169
+ # With no prompt ID, --pipeline's first prompt is the one to run.
170
+ def adopt_pipeline_head(config)
171
+ return unless config.prompt_id.nil? || config.prompt_id.empty?
172
+
173
+ head = Array(config.pipeline).first
174
+ config.prompt_id = head unless head.nil? || head.empty?
175
+ end
176
+
132
177
  def validate_required_prompt_id(config)
133
178
  return unless config.prompt_id.nil? && config.flags.chat != true && config.flags.fuzzy != true
134
179
 
135
180
  raise AIA::ConfigurationError,
136
- "A prompt ID is required unless using --chat, --fuzzy, or providing context files. Use -h or --help for help."
181
+ "A prompt ID is required unless you use --chat, --fuzzy, --pipeline or --role, " \
182
+ "pipe the prompt in, or run an executable prompt. Context files alone are not a prompt. " \
183
+ "Use -h or --help for help."
137
184
  end
138
185
 
139
186
  def process_role_configuration(config)
140
- role = config.prompts.role
187
+ prompts = config.prompts
188
+ role = prompts.role
141
189
  return if role.nil? || role.empty?
142
190
 
143
- roles_prefix = config.prompts.roles_prefix
191
+ roles_prefix = prompts.roles_prefix
144
192
  unless AIA::SkillUtils.path_based_id?(role) || roles_prefix.nil? || roles_prefix.empty? || role.start_with?(roles_prefix)
145
- config.prompts.role = "#{roles_prefix}/#{role}"
146
- role = config.prompts.role
193
+ role = "#{roles_prefix}/#{role}"
194
+ prompts.role = role
147
195
  end
148
196
 
149
- config.prompts.roles_dir ||= File.join(config.prompts.dir, roles_prefix.to_s)
150
-
151
197
  return if config.flags&.chat == true
152
198
 
153
199
  return unless config.prompt_id.nil? || config.prompt_id.empty?
154
- return if role.nil? || role.empty?
155
200
  config.prompt_id = role
156
- config.pipeline.prepend(config.prompt_id)
157
- config.prompts.role = ''
201
+ config.pipeline.prepend(role)
202
+ prompts.role = ''
158
203
  end
159
204
 
160
205
  def validate_plugins_dir(config)
@@ -172,9 +217,10 @@ module AIA
172
217
  end
173
218
 
174
219
  def normalize_boolean_flags(config)
175
- normalize_boolean_flag(config.flags, :chat)
176
- normalize_boolean_flag(config.flags, :fuzzy)
177
- normalize_boolean_flag(config.flags, :consensus)
220
+ flags = config.flags
221
+ normalize_boolean_flag(flags, :chat)
222
+ normalize_boolean_flag(flags, :fuzzy)
223
+ normalize_boolean_flag(flags, :consensus)
178
224
  end
179
225
 
180
226
  def normalize_boolean_flag(flags_section, flag)
@@ -211,21 +257,23 @@ module AIA
211
257
  else
212
258
  label = mcp_filter_active?(config) ? "Active" : "Configured"
213
259
  puts "#{label} MCP servers:\n\n"
214
- servers.each do |server|
215
- name = AIA::Utility.server_name(server) || '(unnamed)'
216
- transport = server[:transport] || server['transport'] || {}
217
- command = transport[:command] || transport['command'] || server[:command] || server['command'] || '(no command)'
218
- args = transport[:args] || transport['args'] || server[:args] || server['args'] || []
219
- args_str = args.empty? ? '' : " #{args.join(' ')}"
220
- puts " #{name}"
221
- puts " command: #{command}#{args_str}"
222
- puts
223
- end
260
+ servers.each { |server| print_mcp_server(McpServerConfig.from_hash(server)) }
224
261
  end
225
262
 
226
263
  :early_exit
227
264
  end
228
265
 
266
+ def print_mcp_server(server_config)
267
+ args_str = server_config.args.empty? ? '' : " #{server_config.args.join(' ')}"
268
+ puts " #{server_config.name || '(unnamed)'}"
269
+ if server_config.command.nil? && server_config.url
270
+ puts " url: #{server_config.url}"
271
+ else
272
+ puts " command: #{server_config.command || '(no command)'}#{args_str}"
273
+ end
274
+ puts
275
+ end
276
+
229
277
  def handle_list_tools(config)
230
278
  return unless config.list_tools
231
279
 
@@ -266,8 +314,8 @@ module AIA
266
314
  end
267
315
 
268
316
  def print_tool_terminal(tool, width, indent)
269
- name = tool.respond_to?(:name) ? tool.name : tool.class.name
270
- desc = tool.respond_to?(:description) ? tool.description.to_s.strip : ''
317
+ name = ToolIntrospection.tool_name(tool)
318
+ desc = ToolIntrospection.tool_description(tool).strip
271
319
 
272
320
  puts " #{name}"
273
321
  unless desc.empty?
@@ -278,6 +326,7 @@ module AIA
278
326
  puts
279
327
  end
280
328
 
329
+ # :reek:TooManyStatements -- sequential markdown report: header, local tools section, one section per MCP server
281
330
  def list_tools_markdown(local_tools, mcp_tool_groups)
282
331
  total = local_tools.size + mcp_tool_groups.values.sum(&:size)
283
332
  sources = 1 + mcp_tool_groups.size
@@ -301,8 +350,8 @@ module AIA
301
350
  end
302
351
 
303
352
  def print_tool_markdown(tool)
304
- name = tool.respond_to?(:name) ? tool.name : tool.class.name
305
- desc = tool.respond_to?(:description) ? tool.description.to_s.strip : ''
353
+ name = ToolIntrospection.tool_name(tool)
354
+ desc = ToolIntrospection.tool_description(tool).strip
306
355
 
307
356
  puts "### `#{name}`"
308
357
  puts
@@ -318,18 +367,13 @@ module AIA
318
367
  end
319
368
  end
320
369
 
370
+ # The servers --mcp-use/--mcp-skip keep. --require libraries are loaded
371
+ # first and entries naming a RubyLLM::MCP subclass are resolved to it,
372
+ # exactly as a session does before connecting.
321
373
  def filter_mcp_servers(config)
322
- servers = config.mcp_servers || []
323
- use_list = Array(config.mcp_use)
324
- skip_list = Array(config.mcp_skip)
325
-
326
- if !use_list.empty?
327
- servers.select { |s| use_list.include?(s[:name] || s['name']) }
328
- elsif !skip_list.empty?
329
- servers.reject { |s| skip_list.include?(s[:name] || s['name']) }
330
- else
331
- servers
332
- end
374
+ AIA::ToolLoader.require_libs(config)
375
+ selected = AIA::MCPDiscovery.select(config.mcp_servers || [], use: config.mcp_use, skip: config.mcp_skip)
376
+ AIA::MCPDiscovery.new.resolve_entries(selected)
333
377
  end
334
378
 
335
379
  def mcp_filter_active?(config)
@@ -359,42 +403,34 @@ module AIA
359
403
  :early_exit
360
404
  end
361
405
 
362
- def load_local_tools(config)
363
- # Load required libraries
364
- Array(config.require_libs).each do |lib|
365
- require lib
366
- rescue LoadError => e
367
- $stderr.puts "Warning: Failed to require '#{lib}': #{e.message}"
368
- $stderr.puts "Hint: Make sure the gem is installed: gem install #{lib}"
369
- rescue StandardError => e
370
- $stderr.puts "Warning: Error in library '#{lib}': #{e.class} - #{e.message}"
371
- end
406
+ # --list-roles, from the configured prompts directory and roles prefix.
407
+ def handle_list_roles(config)
408
+ return unless config.respond_to?(:list_roles) && config.list_roles
372
409
 
373
- # Load tool files
374
- Array(config.tools&.paths).each do |path|
375
- expanded = File.expand_path(path)
376
- if File.exist?(expanded)
377
- require expanded
378
- else
379
- $stderr.puts "Warning: Tool file not found: #{path}"
380
- end
381
- rescue LoadError, StandardError => e
382
- $stderr.puts "Warning: Failed to load tool '#{path}': #{e.message}"
383
- end
410
+ prompts = config.prompts
411
+ puts AIA::RoleCatalog.listing(prompts.dir, prompts.roles_prefix, extname: prompts.extname)
412
+ :early_exit
413
+ end
384
414
 
385
- # Scan ObjectSpace for RubyLLM::Tool subclasses
386
- ObjectSpace.each_object(Class).select do |klass|
387
- next false unless defined?(RubyLLM::Tool) && klass < RubyLLM::Tool
415
+ # Every -m MODEL=ROLE role must exist in the configured prompts directory.
416
+ def validate_model_roles(config)
417
+ prompts = config.prompts
418
+ Array(config.models).each do |spec|
419
+ role = spec.respond_to?(:role) ? spec.role : nil
420
+ next if role.nil? || role.to_s.empty?
388
421
 
389
- begin
390
- klass.new
391
- true
392
- rescue StandardError
393
- false
394
- end
422
+ AIA::RoleCatalog.validate!(role, dir: prompts.dir, prefix: prompts.roles_prefix, extname: prompts.extname)
395
423
  end
396
424
  end
397
425
 
426
+ # The local tools a session would offer: loaded the same way
427
+ # (--require gems, --tools files, lazily loaded tool gems) and narrowed
428
+ # by --allowed-tools / --rejected-tools.
429
+ def load_local_tools(config)
430
+ ToolLoader.load_tools(config)
431
+ ToolLoader.filtered_tools(config)
432
+ end
433
+
398
434
  def first_sentences(text, count)
399
435
  normalized = text.gsub(/\s*\n\s*/, ' ').gsub(/\s{2,}/, ' ').strip
400
436
  sentences = normalized.scan(/[^.!?]*[.!?]/)
@@ -402,75 +438,35 @@ module AIA
402
438
  result.empty? ? normalized : result
403
439
  end
404
440
 
405
- # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
441
+ # :reek:TooManyStatements -- per-server connect loop with progress prints on each outcome path
406
442
  def load_mcp_tools_grouped(config)
407
443
  servers = filter_mcp_servers(config)
408
444
  return {} if servers.empty?
409
445
 
410
- quiet_mcp_logger
411
-
412
- groups = {}
413
- default_timeout = 8_000
414
-
415
- # rubocop:disable Metrics/BlockLength
416
- servers.each do |server|
417
- name = AIA::Utility.server_name(server)
418
- transport = server[:transport] || server['transport'] || {}
419
- command = transport[:command] || transport['command'] || server[:command] || server['command']
420
- args = transport[:args] || transport['args'] || server[:args] || server['args'] || []
421
- env = transport[:env] || transport['env'] || server[:env] || server['env'] || {}
446
+ servers.each_with_object({}) do |server, groups|
447
+ server_config = McpServerConfig.from_hash(server)
448
+ $stderr.print "MCP: Connecting to #{server_config.name}..."
449
+ $stderr.flush
422
450
 
423
- raw_timeout = server[:timeout] || server['timeout'] || default_timeout
424
- timeout = raw_timeout.to_i < 1000 ? (raw_timeout.to_i * 1000) : raw_timeout.to_i
425
- timeout = [timeout, 30_000].min
426
-
427
- mcp_config = { command: command, args: Array(args) }
428
- mcp_config[:env] = env unless env.empty?
429
-
430
- begin
431
- $stderr.print "MCP: Connecting to #{name}..."
432
- $stderr.flush
433
-
434
- client = begin
435
- RubyLLM::MCP.add_client(
436
- name: name, transport_type: :stdio,
437
- config: mcp_config, request_timeout: timeout, start: false
438
- )
439
- rescue ArgumentError
440
- RubyLLM::MCP.add_client(
441
- name: name, transport_type: :stdio,
442
- config: mcp_config, start: false
443
- )
444
- end
445
-
446
- client = RubyLLM::MCP.clients[name]
447
- client.start
448
-
449
- if client.alive?
450
- server_tools = client.tools rescue []
451
- groups[name] = server_tools
452
- $stderr.puts " #{server_tools.size} tools"
453
- else
454
- $stderr.puts " failed"
455
- end
456
- rescue StandardError => e
457
- $stderr.puts " error: #{e.message}"
458
- end
459
- # rubocop:enable Metrics/BlockLength
451
+ tools = collect_server_tools(server, server_config)
452
+ groups[server_config.name] = tools
453
+ $stderr.puts " #{tools.size} tools"
454
+ rescue StandardError => e
455
+ $stderr.puts " error: #{e.message}"
460
456
  end
461
- # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
462
-
463
- groups
464
457
  end
465
- # rubocop:enable Metrics/ModuleLength
466
458
 
467
- def quiet_mcp_logger
468
- return unless defined?(RubyLLM::MCP) && RubyLLM::MCP.respond_to?(:config)
469
- mcp_config = RubyLLM::MCP.config
470
- return unless mcp_config.respond_to?(:logger=)
471
- quiet = Logger.new(File::NULL)
472
- mcp_config.logger = quiet
459
+ # Build the server the way MCPConnectionManager does (RobotLab::MCP.build,
460
+ # so --list-tools shows exactly the RubyLLM::MCP::Tools a robot would be
461
+ # handed) and return its tools. Connection failures raise. The server is
462
+ # closed before returning.
463
+ def collect_server_tools(server, server_config)
464
+ mcp = RobotLab::MCP.build(MCPConfigNormalizer.normalize(server))
465
+ Timeout.timeout(server_config.timeout_ms / 1000.0) { mcp.tools }
466
+ ensure
467
+ mcp&.close
473
468
  end
469
+ # rubocop:enable Metrics/ModuleLength
474
470
 
475
471
  def handle_completion_script(config)
476
472
  return unless config.completion
@@ -482,27 +478,19 @@ module AIA
482
478
  def generate_completion_script(shell)
483
479
  script_path = File.join(File.dirname(__FILE__), "../aia_completion.#{shell}")
484
480
 
485
- if File.exist?(script_path)
486
- puts File.read(script_path)
487
- else
488
- $stderr.puts "ERROR: The shell '#{shell}' is not supported or the completion script is missing."
481
+ unless File.exist?(script_path)
482
+ raise AIA::ConfigurationError,
483
+ "ERROR: The shell '#{shell}' is not supported (use bash, zsh or fish)."
489
484
  end
490
- end
491
485
 
492
- def validate_final_prompt_requirements(config)
493
- chat_mode = config.flags.chat == true
494
- fuzzy_mode = config.flags.fuzzy == true
495
- no_prompt = config.prompt_id.nil? || config.prompt_id.empty?
496
- no_context = config.context_files.nil? || config.context_files.empty?
497
- return unless !chat_mode && !fuzzy_mode && no_prompt && no_context
498
- raise AIA::ConfigurationError,
499
- "A prompt ID is required unless using --chat, --fuzzy, or providing context files. Use -h or --help for help."
486
+ puts File.read(script_path)
500
487
  end
501
488
 
502
489
  def prepare_pipeline(config)
503
- return if config.prompt_id.nil? || config.prompt_id.empty? || config.prompt_id == config.pipeline.first
490
+ prompt_id = config.prompt_id
491
+ return if prompt_id.nil? || prompt_id.empty? || prompt_id == config.pipeline.first
504
492
 
505
- config.pipeline.prepend(config.prompt_id)
493
+ config.pipeline.prepend(prompt_id)
506
494
  end
507
495
 
508
496
  def validate_pipeline_prompts(config)
@@ -513,7 +501,7 @@ module AIA
513
501
  config.pipeline.each do |prompt_id|
514
502
  next if prompt_id.nil? || prompt_id.empty? || prompt_id == '__FUZZY_SEARCH__' || prompt_id == '__EXECUTABLE_PROMPT__'
515
503
 
516
- prompt_file_path = File.join(config.prompts.dir, "#{prompt_id}#{config.prompts.extname}")
504
+ prompt_file_path = AIA::SkillUtils.prompt_file_path(prompt_id, dir: config.prompts.dir, extname: config.prompts.extname)
517
505
  unless File.exist?(prompt_file_path)
518
506
  $stderr.puts "Error: Prompt ID '#{prompt_id}' does not exist at #{prompt_file_path}"
519
507
  and_exit = true