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
@@ -10,6 +10,7 @@
10
10
  # resettable default instance (reset via ToolLoader.reset_instance! or AIA.reset!).
11
11
 
12
12
  module AIA
13
+ # :reek:TooManyMethods -- class-level delegators mirror the instance API; each loading step is its own small, testable method
13
14
  class ToolLoader
14
15
  class << self
15
16
  # Returns the shared default instance, creating it on first call.
@@ -27,6 +28,7 @@ module AIA
27
28
  def cached_tools = instance.cached_tools
28
29
  def clear_cache! = instance.clear_cache!
29
30
  def load_tools(config) = instance.load_tools(config)
31
+ def require_libs(config) = instance.require_libs(config)
30
32
  def filtered_tools(config) = instance.filtered_tools(config)
31
33
  def discover_tools = instance.discover_tools
32
34
  def eager_load_gem_tools = instance.eager_load_gem_tools
@@ -53,17 +55,9 @@ module AIA
53
55
 
54
56
  # Load tools from require_libs and tool paths, then cache the result.
55
57
  # Subsequent calls to RobotFactory.build skip this entirely if cache exists.
58
+ # :reek:TooManyStatements -- sequential phases: require_libs, tool files, eager loads, discovery cache
56
59
  def load_tools(config)
57
- Array(config.require_libs).each do |lib|
58
- require lib
59
- rescue LoadError
60
- # Not yet active — activate it (and its deps) via RubyGems, then retry
61
- if activate_unbundled_gem(lib)
62
- require lib rescue warn("Warning: Failed to require '#{lib}' after activation")
63
- else
64
- $stderr.puts "Warning: Failed to require '#{lib}': gem not found"
65
- end
66
- end
60
+ require_libs(config)
67
61
 
68
62
  # Load tool files from paths
69
63
  Array(config.tools&.paths).each do |path|
@@ -89,11 +83,29 @@ module AIA
89
83
  tools = discover_tools
90
84
  @tool_cache = tools
91
85
  config.loaded_tools = tools
92
- config.tool_names = tools.map { |t| t.respond_to?(:name) ? t.name : t.class.name }.join(', ')
86
+ config.tool_names = tools.map { |t| ToolIntrospection.tool_name(t) }.join(', ')
87
+ end
88
+
89
+ # Require each --require library, activating an unbundled gem first when
90
+ # needed. Safe to call more than once: Kernel#require skips loaded files.
91
+ # Session calls it before connecting MCP servers, so mcp_servers: entries
92
+ # can name RubyLLM::MCP subclasses those libraries define.
93
+ def require_libs(config)
94
+ Array(config.require_libs).each do |lib|
95
+ require lib
96
+ rescue LoadError
97
+ # Not yet active — activate it (and its deps) via RubyGems, then retry
98
+ if activate_unbundled_gem(lib)
99
+ require lib rescue warn("Warning: Failed to require '#{lib}' after activation")
100
+ else
101
+ $stderr.puts "Warning: Failed to require '#{lib}': gem not found"
102
+ end
103
+ end
93
104
  end
94
105
 
95
106
  # Filter tools based on allowed/rejected lists and KBS decisions.
96
- # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
107
+ # :reek:TooManyStatements -- allowed filter, rejected filter, then a name-dedup pass over the tool list
108
+ # :reek:DuplicateMethodCall -- tool_name(t) is applied per element inside three separate filter blocks; no shared scope to hoist into
97
109
  def filtered_tools(config)
98
110
  tools = config.loaded_tools || []
99
111
  allowed = config.tools&.allowed
@@ -102,7 +114,7 @@ module AIA
102
114
  if allowed && !allowed.empty?
103
115
  allowed_list = Array(allowed).map(&:strip).map(&:downcase)
104
116
  tools = tools.select do |t|
105
- name = (t.respond_to?(:name) ? t.name : t.class.name).downcase
117
+ name = ToolIntrospection.tool_name(t).downcase
106
118
  # name is a String; Array#intersect? would raise TypeError
107
119
  allowed_list.any? { |a| name.include?(a) }
108
120
  end
@@ -111,7 +123,7 @@ module AIA
111
123
  if rejected && !rejected.empty?
112
124
  rejected_list = Array(rejected).map(&:strip).map(&:downcase)
113
125
  tools = tools.reject do |t|
114
- name = (t.respond_to?(:name) ? t.name : t.class.name).downcase
126
+ name = ToolIntrospection.tool_name(t).downcase
115
127
  # name is a String; Array#intersect? would raise TypeError
116
128
  rejected_list.any? { |r| name.include?(r) }
117
129
  end
@@ -119,7 +131,7 @@ module AIA
119
131
 
120
132
  seen = {}
121
133
  tools.select do |t|
122
- name = t.respond_to?(:name) ? t.name : t.class.name
134
+ name = ToolIntrospection.tool_name(t)
123
135
  if seen[name]
124
136
  false
125
137
  else
@@ -128,25 +140,53 @@ module AIA
128
140
  end
129
141
  end
130
142
  end
131
- # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
132
143
 
133
144
  # Discover RubyLLM::Tool subclasses from ObjectSpace.
134
- # Skips tools that report themselves as unavailable via #available?.
145
+ # Skips tools that report themselves as unavailable via #available?
146
+ # (reported only under --debug, since that is a deliberate opt-out) and
147
+ # tools whose class body never finished loading (always reported).
135
148
  def discover_tools
136
- ObjectSpace.each_object(Class).select do |klass|
137
- next false unless defined?(RubyLLM::Tool) && klass < RubyLLM::Tool
138
- begin
139
- instance = klass.new
140
- if instance.respond_to?(:available?) && !instance.available?
141
- tool_name = instance.respond_to?(:name) ? instance.name : klass.name
142
- $stderr.puts "Info: Tool '#{tool_name}' is not available, skipping"
143
- next false
144
- end
145
- true
146
- rescue LoadError, StandardError
147
- false
148
- end
149
- end
149
+ return [] unless defined?(RubyLLM::Tool)
150
+
151
+ candidates = ObjectSpace.each_object(Class).select { |klass| klass < RubyLLM::Tool && !mcp_tool_class?(klass) }
152
+ incomplete, complete = candidates.partition { |klass| !implements_execute?(klass) }
153
+ warn_incomplete_tools(incomplete.map { |klass| klass.name || klass.inspect })
154
+ complete.select { |klass| available_tool?(klass) }
155
+ end
156
+
157
+ # True when the tool class can be instantiated and does not report
158
+ # itself unavailable through #available? (reported only under --debug).
159
+ def available_tool?(klass)
160
+ instance = klass.new
161
+ return true unless instance.respond_to?(:available?) && !instance.available?
162
+
163
+ $stderr.puts "Info: Tool '#{ToolIntrospection.tool_name(instance)}' is not available, skipping" if AIA.debug?
164
+ false
165
+ rescue LoadError, StandardError
166
+ false
167
+ end
168
+
169
+ # True for ruby_llm's RubyLLM::MCP::Tool (and subclasses): the wrapper an
170
+ # MCP server's tools arrive in. They come from MCPConnectionManager, never
171
+ # from ObjectSpace, and have no #execute of their own.
172
+ def mcp_tool_class?(klass)
173
+ defined?(RubyLLM::MCP::Tool) ? klass <= RubyLLM::MCP::Tool : false
174
+ end
175
+
176
+ # True when the tool class defines its own #execute. A class whose body
177
+ # raised partway through (e.g. a gem written against an older RubyLLM
178
+ # tool DSL) still inherits RubyLLM::Tool's abstract #execute and would
179
+ # fail with NotImplementedError on the first tool call.
180
+ def implements_execute?(klass)
181
+ klass.instance_method(:execute).owner != RubyLLM::Tool
182
+ end
183
+
184
+ # One summary line for tool classes rejected by #implements_execute?.
185
+ def warn_incomplete_tools(names)
186
+ return if names.empty?
187
+
188
+ $stderr.puts "Warning: #{names.size} tool(s) did not finish loading and were skipped " \
189
+ "(the gem providing them may need updating): #{names.sort.join(', ')}"
150
190
  end
151
191
 
152
192
  # Activate a gem that isn't yet active by asking RubyGems to activate it.
@@ -8,15 +8,16 @@
8
8
  module AIA
9
9
  module ToolUtility
10
10
  def tools?
11
- return true if AIA.config&.tool_names && !AIA.config.tool_names.empty?
11
+ names = AIA.config&.tool_names
12
+ return true if names && !names.empty?
12
13
  total_tool_count.positive?
13
14
  end
14
15
 
15
16
  def total_tool_count
16
- local = Array(AIA.config&.loaded_tools).size
17
- return local if AIA.config&.flags&.no_mcp
18
- mcp = defined?(RubyLLM::MCP) ? RubyLLM::MCP.clients.sum { |_, c| c.tools.count } : 0
19
- local + mcp
17
+ config = AIA.config
18
+ local = Array(config&.loaded_tools).size
19
+ return local if config&.flags&.no_mcp
20
+ local + (config&.mcp_server_tool_counts || {}).values.sum
20
21
  end
21
22
 
22
23
  def user_tools?
@@ -13,12 +13,14 @@ module AIA
13
13
  "Use this when you need to create, assign, track, or manage tasks. " \
14
14
  "Pass a natural language description of what you need done on the task board."
15
15
 
16
- param :request, type: :string, required: true,
17
- desc: "Natural language description of the task board operation " \
18
- "(e.g., 'create a research task about recessions assigned to Tobor with labels research, economics')"
16
+ parameter :request, type: :string, required: true,
17
+ description: "Natural language description of the task board operation " \
18
+ "(e.g., 'create a research task about recessions assigned to Tobor with labels research, economics')"
19
19
 
20
+ # Offered whenever TrakFlow is installed; the task board starts when
21
+ # Foreman first needs it.
20
22
  def available?
21
- AIA.task_coordinator&.available? || false
23
+ AIA::TaskBoard.gem_available?
22
24
  end
23
25
 
24
26
  def execute(request:, **_params)
@@ -14,18 +14,18 @@ module AIA
14
14
  "skills that define its role, and/or a system prompt. The " \
15
15
  "newcomer joins the crew right away and can be addressed with @name."
16
16
 
17
- param :name, type: :string, required: true,
18
- desc: "Unique name for the new robot, e.g. 'researcher'. Reserved: 'crew'."
19
- param :model, type: :string,
20
- desc: "Optional provider/model, e.g. 'ollama/qwen3.6:latest' or 'gpt-4o'. " \
21
- "Omit (or pass '-') to inherit the chief's model and provider."
22
- param :skills, type: :string,
23
- desc: "Optional comma-separated skill ids to assign as the robot's role " \
24
- "(e.g. 'security-review,ruby-style'). Each skill's content becomes " \
25
- "part of its system prompt. Use this to give crew members distinct jobs."
26
- param :system_prompt, type: :string,
27
- desc: "Optional extra system prompt, appended after any skills — its role, " \
28
- "persona, and instructions."
17
+ parameter :name, type: :string, required: true,
18
+ description: "Unique name for the new robot, e.g. 'researcher'. Reserved: 'crew'."
19
+ parameter :model, type: :string,
20
+ description: "Optional provider/model, e.g. 'ollama/qwen3.6:latest' or 'gpt-4o'. " \
21
+ "Omit (or pass '-') to inherit the chief's model and provider."
22
+ parameter :skills, type: :string,
23
+ description: "Optional comma-separated skill ids to assign as the robot's role " \
24
+ "(e.g. 'security-review,ruby-style'). Each skill's content becomes " \
25
+ "part of its system prompt. Use this to give crew members distinct jobs."
26
+ parameter :system_prompt, type: :string,
27
+ description: "Optional extra system prompt, appended after any skills — its role, " \
28
+ "persona, and instructions."
29
29
 
30
30
  def execute(name:, model: nil, skills: nil, system_prompt: nil)
31
31
  robot = AIA::Crew.recruit(build_spec(name, model, skills, system_prompt))
@@ -14,13 +14,13 @@ module AIA
14
14
  "role from the given skills and/or system prompt. Use this to " \
15
15
  "repurpose a member or recover one that went off task."
16
16
 
17
- param :name, type: :string, required: true,
18
- desc: "Name of the existing crew member to reset (cannot be the chief)."
19
- param :skills, type: :string,
20
- desc: "Optional comma-separated skill ids to assign as the new role " \
21
- "(e.g. 'testing,performance')."
22
- param :system_prompt, type: :string,
23
- desc: "Optional extra system prompt, appended after any skills."
17
+ parameter :name, type: :string, required: true,
18
+ description: "Name of the existing crew member to reset (cannot be the chief)."
19
+ parameter :skills, type: :string,
20
+ description: "Optional comma-separated skill ids to assign as the new role " \
21
+ "(e.g. 'testing,performance')."
22
+ parameter :system_prompt, type: :string,
23
+ description: "Optional extra system prompt, appended after any skills."
24
24
 
25
25
  def execute(name:, skills: nil, system_prompt: nil)
26
26
  prompt = system_prompt.to_s.strip
@@ -9,26 +9,27 @@
9
9
  require "json"
10
10
 
11
11
  module AIA
12
+ # :reek:DataClump -- each execute_<action> dispatch target receives the same LLM tool-call context
12
13
  class TaskBoardTool < RubyLLM::Tool
13
14
  description "Manage a shared task board. Create tasks for other robots, " \
14
15
  "check what's ready, claim tasks, and report completion."
15
16
 
16
- param :action, type: :string, required: true,
17
- desc: "One of: create, plan, ready, claim, complete, block, status"
18
- param :title, type: :string,
19
- desc: "Task title (for create/plan actions)"
20
- param :assignee, type: :string,
21
- desc: "Robot name to assign to (for create/claim/ready)"
22
- param :labels, type: :string,
23
- desc: "Comma-separated labels (for create)"
24
- param :blocked_by, type: :string,
25
- desc: "Comma-separated blocker task IDs (for create)"
26
- param :steps, type: :string,
27
- desc: "JSON array of step objects [{title:, assignee:}] (for plan)"
28
- param :task_id, type: :string,
29
- desc: "Task ID (for claim/complete/block)"
30
- param :result, type: :string,
31
- desc: "Result summary (for complete) or reason (for block)"
17
+ parameter :action, type: :string, required: true,
18
+ description: "One of: create, plan, ready, claim, complete, block, status"
19
+ parameter :title, type: :string,
20
+ description: "Task title (for create/plan actions)"
21
+ parameter :assignee, type: :string,
22
+ description: "Robot name to assign to (for create/claim/ready)"
23
+ parameter :labels, type: :string,
24
+ description: "Comma-separated labels (for create)"
25
+ parameter :blocked_by, type: :string,
26
+ description: "Comma-separated blocker task IDs (for create)"
27
+ parameter :steps, type: :string,
28
+ description: "JSON array of step objects [{title:, assignee:}] (for plan)"
29
+ parameter :task_id, type: :string,
30
+ description: "Task ID (for claim/complete/block)"
31
+ parameter :result, type: :string,
32
+ description: "Result summary (for complete) or reason (for block)"
32
33
 
33
34
  # Never auto-discovered onto primary robots. Only Foreman
34
35
  # (built by DelegateToForemanTool) receives this tool explicitly.
@@ -11,7 +11,9 @@ require "trak_flow"
11
11
  module AIA
12
12
  class TrakFlowBridge
13
13
  def initialize
14
- @db = connect_database
14
+ @db = connect_database
15
+ @steps = Hash.new { |hash, key| hash[key] = [] } # prompt ID => this plan's unstarted steps
16
+ @current = {} # prompt ID => the step now running
15
17
  end
16
18
 
17
19
  # Whether a TrakFlow project is initialized and the database is accessible.
@@ -26,6 +28,7 @@ module AIA
26
28
  #
27
29
  # @param pipeline [Array<String>] prompt IDs in pipeline order
28
30
  # @return [String, nil] summary of created plan
31
+ # :reek:TooManyStatements -- plan build: one child task per pipeline step, chained by blocking dependencies
29
32
  def create_plan_from_pipeline(pipeline)
30
33
  return nil unless available?
31
34
 
@@ -39,6 +42,7 @@ module AIA
39
42
  title: "Step #{i + 1}: #{prompt_id}",
40
43
  type: "task"
41
44
  })
45
+ @steps[prompt_id] << step
42
46
 
43
47
  if prev_step
44
48
  @db.add_dependency(TrakFlow::Models::Dependency.new(
@@ -59,27 +63,28 @@ module AIA
59
63
 
60
64
  # Update a task's status in TrakFlow.
61
65
  #
62
- # @param step_name [String] task title to find
66
+ # @param step_name [String] the prompt ID of a step in the plan this bridge created
63
67
  # @param status [Symbol] :started, :completed, or :failed
64
68
  # @param reason [String, nil] reason for failure
65
69
  def update_step_status(step_name, status, reason: nil)
66
70
  return unless available?
67
71
 
68
- task = find_task_by_title(step_name)
72
+ task = step_for(step_name, status)
69
73
  return unless task
70
74
 
71
75
  case status
72
76
  when :started
73
77
  task.status = "in_progress"
74
- @db.update_task(task)
75
78
  when :completed
76
79
  task.close!(reason: reason || "Completed")
77
- @db.update_task(task)
78
80
  when :failed
79
81
  task.status = "blocked"
80
82
  task.append_trace("blocked", reason) if reason
81
- @db.update_task(task)
83
+ else
84
+ return
82
85
  end
86
+
87
+ @db.update_task(task)
83
88
  rescue StandardError => e
84
89
  $stderr.puts "Warning: TrakFlow status update failed: #{e.message}"
85
90
  end
@@ -155,7 +160,7 @@ module AIA
155
160
 
156
161
  # Connect to the TrakFlow database if a project is initialized.
157
162
  def connect_database
158
- return nil unless TrakFlow.initialized?
163
+ return nil unless TaskBoard.ensure_project!
159
164
 
160
165
  db = TrakFlow::Storage::Database.new(TrakFlow.database_path)
161
166
  db.connect
@@ -164,10 +169,13 @@ module AIA
164
169
  nil
165
170
  end
166
171
 
167
- # Find a task by its title (partial match).
168
- def find_task_by_title(title)
169
- tasks = @db.list_tasks(title: title)
170
- tasks.first
172
+ # The step this bridge created for +prompt_id+. :started takes the next
173
+ # unstarted one (a prompt can appear twice); later updates reuse it.
174
+ # Steps are never looked up by title, so older plans can't collide.
175
+ def step_for(prompt_id, status)
176
+ return @current[prompt_id] unless status == :started
177
+
178
+ @current[prompt_id] = @steps[prompt_id].shift
171
179
  end
172
180
  end
173
181
  end
@@ -6,21 +6,24 @@
6
6
  # Replaces ad-hoc instance variable flags on AIA.config.
7
7
  #
8
8
  # Only one special mode may be requested per turn (mutual exclusion).
9
- # Use TurnState#request(mode, **opts) to enqueue a mode — this clears
10
- # all other force_* flags before setting the new one. Assigning the
11
- # attr_accessors directly bypasses mutual exclusion (for backward compat
12
- # and direct test assertions).
9
+ # TurnState#request(mode, **opts) enqueues a mode and clears all other
10
+ # force_* flags. #consume! hands the active mode to its handler and
11
+ # clears it. The force_* flags are read-only from outside.
13
12
 
14
13
  module AIA
14
+ # :reek:TooManyInstanceVariables -- one boolean flag per exclusive mode plus spawn/mcp details; a Hash would lose the attr_accessor API
15
15
  class TurnState
16
16
  # Exclusive mode flags — only one may be active at a time via #request.
17
17
  EXCLUSIVE_MODES = %i[
18
18
  verify decompose concurrent_mcp debate delegate spawn orchestrate
19
19
  ].freeze
20
20
 
21
- attr_accessor :force_verify, :force_decompose, :force_concurrent_mcp,
22
- :force_debate, :force_delegate, :force_spawn, :spawn_type,
23
- :spawn_spec, :force_orchestrate, :active_mcp_servers
21
+ attr_reader :force_verify, :force_decompose, :force_concurrent_mcp,
22
+ :force_debate, :force_delegate, :force_spawn, :spawn_type,
23
+ :spawn_spec, :force_orchestrate
24
+
25
+ # Per-turn MCP server filter; not an exclusive mode.
26
+ attr_accessor :active_mcp_servers
24
27
 
25
28
  def initialize
26
29
  clear!
@@ -32,8 +35,9 @@ module AIA
32
35
  #
33
36
  # @param mode [Symbol] one of EXCLUSIVE_MODES
34
37
  # @param type [String, nil] specialist type (only relevant for :spawn)
38
+ # @param spec [Hash, nil] explicit specialist spec (only relevant for :spawn)
35
39
  # @raise [ArgumentError] if mode is not one of EXCLUSIVE_MODES
36
- def request(mode, type: nil)
40
+ def request(mode, type: nil, spec: nil)
37
41
  unless EXCLUSIVE_MODES.include?(mode)
38
42
  raise ArgumentError, "Unknown TurnState mode: #{mode.inspect}. Valid: #{EXCLUSIVE_MODES.join(', ')}"
39
43
  end
@@ -48,10 +52,30 @@ module AIA
48
52
  when :delegate then @force_delegate = true
49
53
  when :spawn then @force_spawn = true
50
54
  @spawn_type = type
55
+ @spawn_spec = spec
51
56
  when :orchestrate then @force_orchestrate = true
52
57
  end
53
58
  end
54
59
 
60
+ # Take the active mode for handling and clear it.
61
+ #
62
+ # @return [Hash, nil] { mode:, spawn_type:, spawn_spec: }, or nil when no mode is active
63
+ def consume!
64
+ mode = active_mode
65
+ return nil unless mode
66
+
67
+ taken = { mode: mode, spawn_type: @spawn_type, spawn_spec: @spawn_spec }
68
+ clear_exclusive_flags!
69
+ taken
70
+ end
71
+
72
+ # Clear +mode+ if it is the active mode; leave any other mode alone.
73
+ #
74
+ # @param mode [Symbol] one of EXCLUSIVE_MODES
75
+ def clear_mode(mode)
76
+ clear_exclusive_flags! if active_mode == mode
77
+ end
78
+
55
79
  def clear!
56
80
  @force_verify = false
57
81
  @force_decompose = false