ruby_llm-team 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 276088260e61f9aeed5607c1e613f408ff4c58cf777cae74e6fe01d8890da170
+  data.tar.gz: 110604d8bb1288218f78bd5ef2285f2d380a0ebad64f29185d23f45c1fd6ce5e
+SHA512:
+  metadata.gz: 12067c8dc5622ddfb3355a007b5282f65b231ed0d22e719b311aa07d7fd91f91a3c5df1e21a42e670f6d1a9989f8fd510ccf58381e8cb9df8c1bb51c8f24fc9a
+  data.tar.gz: bd7c200b51eb79f6fb5553cfc1b4634c6ae392c35d3c82bf0fcdd077ce2425d54e5e3522d1af96cc0087eba1f8756fa4ee4f43c998e6dbad8ed35fd9a6deecf0

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.1.0 — experimental
+
+First public release. The API is deliberately small but not yet stable: artifact ordering,
+error types, and trace serialization all changed shortly before this release. Pin an exact
+version, and read [docs/DECISIONS.md](docs/DECISIONS.md) for what the gem refuses to do and
+why — those refusals are the stable part.
+
+### Added
+
+- Named immutable artifact versions with `as:`/`from:` handoffs and the thin `Team#run` API.
+- Machine-readable traces: `Session#to_h`/`#to_json` with per-call and run-total best-known
+  token usage; prompts and results export only with `include_content: true`.
+- Typed `BudgetExceededError < CollaborationError` for budget exhaustion.
+- `examples/code_review/` — parallel fan-out/fan-in with a VCR-replayed spec and a
+  line comparison against the upstream plain-Ruby pattern.
+
+### Fixed
+
+- Artifact versions are reserved in submission order, so `artifact(name)` is deterministic
+  when parallel work completes out of order.
+- Non-`StandardError` crashes finalize their call as `:failed` and re-raise instead of
+  leaving it `:running` with a burned budget slot.
+- Fiber siblings settle before a crash propagates; thread joins no longer mask the first crash.
+- A coworker instance delegating back into its own call fails with a clear error instead of
+  `deadlock; recursive locking`.
+- Duplicate coworkers in one `parallel` batch are rejected before reserving budget instead of
+  silently dropping results.
+- `share_context: false` sessions no longer record handoff inputs the coworker never received.
+
+### Changed
+
+- `Run#step` omitted `from:` now hands over every completed artifact, matching `Session#ask`.
+- The published gem contains only `lib/`, README, CHANGELOG, and LICENSE.
+
+### Foundation
+
+- Coworker registry, `delegate_work`/`ask_question` tools, session call budgets,
+  thread/fiber `parallel`, selected handoffs, and the Markdown trace.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 JetThoughts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,215 @@
+# RubyLLM::Team
+
+**Several RubyLLM agents, one run you can audit.** Team gives a multi-agent workflow the
+things you would otherwise hand-roll: named handoffs between agents, one call budget for the
+whole run, safe fan-out, and a trace showing the exact prompt every agent received.
+
+[![CI](https://github.com/jetthoughts/ruby_llm-team/actions/workflows/ci.yml/badge.svg)](https://github.com/jetthoughts/ruby_llm-team/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-3.1%2B-CC342D)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.txt)
+
+It is a small library, not a framework. Your workflow stays ordinary Ruby.
+
+## Do I need this?
+
+You do **not** need Team for one agent, or two agents in a straight line. `Agent#ask` is enough.
+
+You start needing it at the point below — when several agents share work and you have to answer
+"which version did the editor actually review?" and "why did this run cost 40 calls?"
+
+| You are writing this by hand | Team gives you |
+| --- | --- |
+| A hash of results, plus rules for which version is "current" | Named artifact versions with explicit `as:` / `from:` handoffs |
+| A counter so one runaway loop cannot bill you forever | One atomic call budget for the run, across threads and fibers, bounded by default |
+| `Thread.new` per agent and a join that swallows one failure | Fan-out that settles every sibling before raising |
+| `rescue => e` in six places, each shaped differently | One `CollaborationError`, plus typed `BudgetExceededError` |
+| A logger you grep after something goes wrong | A trace with the exact prompt each agent received |
+
+## Install
+
+```ruby
+gem 'ruby_llm-team', require: 'ruby_llm/team'
+```
+
+## Quickstart
+
+```ruby
+require 'ruby_llm/team'
+
+team = RubyLLM::Team.new
+                    .add(:planner, PlannerAgent)
+                    .add(:reviewer, ReviewerAgent)
+
+execution = team.run(max_calls: 4, context: 'Fix one failing test.') do |run|
+  run.step :plan,   with: :planner,  prompt: 'Write a short implementation plan.'
+  run.step :review, with: :reviewer, from: [:plan], prompt: 'Is this plan safe?'
+  run.output :review
+end
+
+execution.output            # => the reviewer's answer
+execution.value(:plan)      # => the plan the reviewer actually saw
+puts execution.to_markdown  # => the full trace
+```
+
+A coworker is anything that responds to `#ask` — a `RubyLLM::Agent` class, an instance, or a
+plain object. That is what makes offline tests trivial (see [Testing](#testing)).
+
+Or hand the tools to a model and let it decide who to consult, with your budget as the limit:
+
+```ruby
+session = team.session(max_calls: 6)
+chat    = RubyLLM.chat.with_tools(*session.tools)
+
+chat.ask('Solid Queue or Sidekiq for a three-person team?')
+session.calls.map(&:coworker)  # => whom the model actually chose to ask
+```
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    App["Your Ruby<br/><i>order, branching, policy</i>"] -->|steps| Session
+    subgraph Team["RubyLLM::Team"]
+        Session["Session<br/><i>budget · failures · trace</i>"]
+        Artifacts[("Artifacts<br/><i>named versions</i>")]
+        Session <--> Artifacts
+    end
+    Session -->|ask| A1["Agent A"]
+    Session -->|ask| A2["Agent B"]
+    Session -->|ask| A3["Agent C"]
+    A1 & A2 & A3 -->|models, tools, retries| RubyLLM["RubyLLM"]
+```
+
+Team sits between your code and your agents. It never owns models, prompts, schemas, retries,
+or your business rules.
+
+## Handoffs are explicit
+
+`as:` names an output. `from:` selects which named outputs the next coworker receives, verbatim.
+Reusing a name publishes a new version, so a revision never silently overwrites its source.
+
+```mermaid
+sequenceDiagram
+    participant W as writer
+    participant E as editor
+    W->>W: ask(as: :draft) → draft@v1
+    W->>E: from: [:draft]
+    E-->>W: review@v1 ("revise")
+    W->>W: ask(as: :draft, from: [:draft, :review]) → draft@v2
+    Note over W,E: artifact(:draft) is v2 — deterministic,<br/>even when work ran in parallel
+```
+
+```ruby
+session.ask(:writer, 'Write the draft', as: :draft, from: [])
+session.ask(:editor, 'Review it',       as: :review, from: [:draft])
+session.ask(:writer, 'Revise it',       as: :draft,  from: %i[draft review])
+
+session.artifact(:draft).version  # => 2
+session.artifact(:draft).sources  # => ["draft@v1 (writer)", "review@v1 (editor)"]
+```
+
+## Running work in parallel
+
+```ruby
+reviews = session.parallel(
+  { security: prompt, performance: prompt, style: prompt },
+  concurrency: :threads   # or :fibers, using the optional async gem
+)
+```
+
+Every task reserves budget up front and appears in the trace. There is deliberately no `limit:`
+— bound concurrency where you own the task list:
+
+```ruby
+tasks.each_slice(3).flat_map { |batch| session.parallel(batch.to_h) }
+```
+
+## Quality loops stay in your Ruby
+
+There is no `refine` or `repair` API. Compose the loop through `session.ask` and every round is
+budget-accounted, traced, and failure-normalized because it is an ordinary call:
+
+```ruby
+session.ask(:writer, task, as: :draft, from: [])
+
+3.times do
+  review = session.ask(:critic, 'Review the draft.', as: :review, from: [:draft])
+  break if review.fetch('verdict') == 'pass'
+
+  session.ask(:writer, 'Revise using every finding.', as: :draft, from: %i[draft review])
+end
+```
+
+Your code owns the predicate and the bound. Swap the critic for a validator and the same shape
+becomes a repair loop.
+
+## Traces
+
+`to_markdown` renders the run for reading. `to_h` / `to_json` export it for tooling, including
+per-call and run-total token usage:
+
+```ruby
+execution.to_h[:usage]   # => { input_tokens: 8_412, output_tokens: 3_120 }
+execution.to_h[:calls]   # => structure, statuses, artifact lineage
+execution.to_json(include_content: true)  # prompts and results, opt-in
+```
+
+Prompts and results are excluded unless you ask for them, so an exported trace is safe to ship.
+The prompt recorded is the exact text the coworker received — context and handoffs included.
+
+## Testing
+
+Coworkers are plain objects, so most tests need no stubbing library and no API key:
+
+```ruby
+writer = Class.new { def ask(_prompt) = 'DRAFT' }
+team   = RubyLLM::Team.new.add(:writer, writer)
+
+execution = team.run { |run| run.step :draft, with: :writer }
+expect(execution.value(:draft)).to eq('DRAFT')
+```
+
+For live workflows, record one VCR cassette and replay it in CI with no key —
+[`spec/ruby_llm/code_review_workflow_spec.rb`](spec/ruby_llm/code_review_workflow_spec.rb)
+shows both patterns side by side.
+
+## Examples
+
+**Copy from [`code_review/`](examples/code_review/) first** — 110 lines, and it shows the whole
+library: parallel fan-out, named handoffs, budget, trace, and a verdict computed in Ruby rather
+than trusted from a model.
+
+| Example | Shape | Run it |
+| --- | --- | --- |
+| [`simple_team.rb`](examples/simple_team.rb) | Two coworkers, one handoff | `ruby examples/simple_team.rb` (no API key) |
+| **[`code_review/`](examples/code_review/)** | **Fan-out / fan-in — start here** | `ruby examples/code_review/workflow.rb [diff]` |
+| [`topic_analyst/`](examples/topic_analyst/) | Parallel research, ranked output | `ruby examples/topic_analyst/workflow.rb "Rails jobs"` |
+| [`decision_panel/`](examples/decision_panel/) | **No Ruby orchestration** — a lead model picks whom to consult | `ruby examples/decision_panel/workflow.rb "your question"` |
+| [`editorial_pipeline.rb`](examples/editorial_pipeline.rb) | Two teams composed in plain Ruby | `ruby examples/editorial_pipeline.rb "your domain"` |
+| [`blog/`](examples/blog/) | _Advanced._ Seven editorial passes, bounded gates, escalation | `ruby examples/blog/workflow.rb` |
+
+The blog example is production-scale on purpose and is the largest thing here; read it for
+patterns, not as a starting point. Live examples need `OPENROUTER_API_KEY`; the research ones
+also use `YDC_API_KEY`.
+
+## What Team is not
+
+No graph DSL, YAML workflows, or role/backstory metaphors. No memory, RAG, MCP, or search. No
+dashboards, persistence, or scheduling — [`ruby_llm-agents`](https://github.com/adham90/ruby_llm-agents)
+owns that Rails layer and Team composes inside it. No hidden retries or model selection: RubyLLM
+owns those.
+
+Reasoning and the evidence behind each refusal: [`docs/DECISIONS.md`](docs/DECISIONS.md).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec          # the suite
+bundle exec rake spec:replay   # recorded workflows, no API key needed
+bundle exec rubocop
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/ruby_llm/team/artifact.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Team
+    # One immutable, successful output published by a coworker call.
+    Artifact = Struct.new(:name, :version, :producer, :sources, :value, :call_index, keyword_init: true)
+  end
+end

data/lib/ruby_llm/team/run.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Team
+    # Imperative convenience wrapper around one Team::Session.
+    class Run
+      OUTPUT_UNSET = Object.new.freeze
+      private_constant :OUTPUT_UNSET
+
+      attr_reader :session
+
+      def initialize(session)
+        @session = session
+      end
+
+      # Omitting +from:+ hands over the latest version of every completed
+      # artifact, matching Session#ask; pass +from: []+ to start clean.
+      def step(name, with:, prompt: nil, from: nil)
+        session.ask(with, prompt || "Complete '#{name}'.", as: name, from: from)
+      end
+
+      def output(name = OUTPUT_UNSET)
+        return selected_output if name.equal?(OUTPUT_UNSET)
+
+        name = name.to_s
+        raise ArgumentError, "No completed artifact named '#{name}'" unless artifact(name)
+
+        @output_name = name
+        self
+      end
+
+      def value(name) = session.value(name)
+      def artifact(name) = session.artifact(name)
+      def artifacts(name) = session.artifacts(name)
+      def calls = session.calls
+      def calls_remaining = session.calls_remaining
+      def to_markdown = session.to_markdown
+      def to_h(include_content: false) = session.to_h(include_content: include_content)
+
+      # Mirrors Session#to_json, positional generator state included, so JSON.generate(run)
+      # works the same way.
+      def to_json(*args, include_content: false) = session.to_json(*args, include_content: include_content)
+
+      private
+
+      def selected_output
+        return unless @output_name
+
+        value(@output_name)
+      end
+    end
+  end
+end

data/lib/ruby_llm/team/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Team
+    VERSION = '0.1.0'
+  end
+end

data/lib/ruby_llm/team.rb

@@ -0,0 +1,584 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'ruby_llm/tool'
+require 'ruby_llm/team/version'
+require 'ruby_llm/team/artifact'
+require 'json'
+require 'securerandom'
+
+module RubyLLM
+  # Groups named coworkers and creates tools for delegating work.
+  #
+  #   team = RubyLLM::Team.new
+  #   team.add(:researcher, ResearcherAgent)
+  #
+  #   session = team.session(max_calls: 8)     # bound what the model may spend
+  #   chat.with_tools(*session.tools)
+  #
+  # The session keeps the artifacts, budget, and trace reachable after the model is done.
+  #
+  # Registered classes are instantiated per call; registered instances are reused.
+  class Team
+    class CollaborationError < StandardError; end
+    # Raised when the session's +max_calls+ budget rejects a call.
+    class BudgetExceededError < CollaborationError; end
+    require 'ruby_llm/team/run'
+
+    # Every call costs money, so a run is bounded unless you say otherwise. This is a smoke
+    # alarm rather than a budget: it stops a runaway, and a workflow that legitimately needs
+    # more says so in one keyword — examples/blog/workflow.rb passes 40. Pass
+    # +max_calls: nil+ for an unbounded run.
+    DEFAULT_MAX_CALLS = 25
+
+    def initialize
+      @agents = {}
+    end
+
+    # Registers +agent+ under +role+ and returns +self+.
+    def add(role, agent)
+      role = role.to_s
+      raise ArgumentError, 'provide a role' if role.empty?
+      raise ArgumentError, 'provide an agent' unless agent
+
+      @agents[role] = agent
+      self
+    end
+
+    # Creates isolated collaboration state for one lead-agent run.
+    def session(max_calls: DEFAULT_MAX_CALLS, share_context: true, context: nil)
+      Session.new(@agents.dup.freeze, max_calls: max_calls, share_context: share_context, context: context)
+    end
+
+    # Executes an ordinary Ruby workflow over one isolated session.
+    def run(max_calls: DEFAULT_MAX_CALLS, share_context: true, context: nil)
+      execution = Run.new(session(max_calls: max_calls, share_context: share_context, context: context))
+      yield execution if block_given?
+      execution
+    end
+
+    # Preserves coworker results, limits calls, and exposes a trace for one run.
+    class Session # rubocop:disable Metrics/ClassLength
+      Call = Struct.new(:action, :coworker, :prompt, :result, :status, :inputs, :artifact, :usage,
+                        keyword_init: true) do
+        def error? = result.is_a?(Hash) && (result.key?(:error) || result.key?('error'))
+        def complete? = status != :running
+        def successful? = complete? && !error?
+      end
+
+      BUDGET_MESSAGE = 'Collaboration call limit reached'
+      private_constant :BUDGET_MESSAGE
+
+      def initialize(agents, max_calls:, share_context:, context:)
+        validate_max_calls(max_calls)
+
+        @agents = agents
+        @max_calls = max_calls
+        @share_context = share_context
+        @context = context&.to_s&.dup&.freeze
+        @calls = []
+        @accepted_calls = 0
+        @mutex = Mutex.new
+        initialize_run_state
+        initialize_agent_mutexes(agents)
+      end
+
+      def collaboration_tools
+        [DelegateWork.new(self), AskQuestion.new(self)]
+      end
+      alias tools collaboration_tools
+
+      def ask(coworker, prompt, as: nil, from: nil)
+        result = consult(
+          action: 'delegate_work', prompt: prompt, coworker: coworker, as: as, from: from
+        )
+        raise_on_error(result)
+      end
+
+      def parallel(tasks, concurrency: :threads, from: nil)
+        runner = parallel_runner(concurrency)
+        reject_duplicate_roles(tasks)
+        work = reserve_batch(tasks, from)
+        send(runner, work).transform_values { |result| raise_on_error(result) }
+      end
+
+      def calls = @mutex.synchronize { @calls.dup.freeze }
+
+      # Calls still allowed by the budget, or +nil+ when the session is unbounded.
+      # Lets an application decide whether an optional pass still fits.
+      def calls_remaining
+        @mutex.synchronize { @max_calls && [@max_calls - @accepted_calls, 0].max }
+      end
+
+      def artifact(name)
+        @mutex.synchronize { @artifacts.fetch(name.to_s, []).last }
+      end
+
+      def artifacts(name)
+        @mutex.synchronize { @artifacts.fetch(name.to_s, []).dup.freeze }
+      end
+
+      def value(name) = artifact(name)&.value
+
+      def to_markdown
+        trace = calls.map.with_index(1) do |call, index|
+          result = call.complete? ? format_result(call.result) : '_In progress_'
+          inputs = call.inputs.empty? ? '_None_' : call.inputs.join(', ')
+          # The whole prompt, handoffs included: "what was actually sent" is the point of
+          # the trace, so the readable format must not be the one that hides it.
+          "## #{index}. #{call.coworker} via #{call.action}\n\n" \
+            "### Inputs\n\n#{inputs}\n\n### Request\n\n#{call.prompt}\n\n" \
+            "### Result\n\n#{result}"
+        end.join("\n\n")
+        @context ? "## Shared team context\n\n#{@context}\n\n#{trace}" : trace
+      end
+
+      # Machine-readable trace: structure and best-known usage by default;
+      # pass +include_content: true+ to also export prompts and results.
+      def to_h(include_content: false)
+        # One snapshot under one lock: calls and artifacts must not disagree.
+        @mutex.synchronize do
+          {
+            calls: @calls.each_with_index.map { |call, index| call_to_h(call, index, include_content) },
+            artifacts: artifacts_to_h,
+            usage: usage_totals(@calls)
+          }
+        end
+      end
+
+      # Accepts JSON's positional generator state so JSON.generate(session) works.
+      def to_json(*_args, include_content: false)
+        JSON.generate(to_h(include_content: include_content))
+      end
+
+      def coworkers = @agents.keys.join(', ')
+
+      def consult(action:, prompt:, coworker:, as: nil, from: nil)
+        role = coworker.to_s
+        perform(reserve(action, role, prompt, as: as || role, from: from), coworker)
+      end
+
+      private
+
+      def initialize_run_state
+        @fence = SecureRandom.hex(4)
+        @artifacts = {}
+        @artifact_serials = Hash.new(0)
+        @reserved_versions = {}
+      end
+
+      def initialize_agent_mutexes(agents)
+        mutexes = {}
+        @agent_mutexes = agents.transform_values { |agent| mutexes[agent.__id__] ||= Mutex.new }
+      end
+
+      def raise_on_error(result)
+        return result unless result.is_a?(Hash) && (result.key?(:error) || result.key?('error'))
+
+        message = result[:error] || result['error']
+        # Flagged by the session, never inferred from the text: a coworker may return an
+        # error that quotes the budget message.
+        raise BudgetExceededError, message if result[:budget_exceeded]
+
+        raise CollaborationError, message
+      end
+
+      def reject_duplicate_roles(tasks)
+        roles = tasks.map { |coworker, _prompt| coworker.to_s }
+        duplicate = roles.tally.find { |_role, count| count > 1 }&.first
+        raise ArgumentError, "duplicate coworker '#{duplicate}' in one parallel batch" if duplicate
+      end
+
+      def validate_max_calls(max_calls)
+        return if max_calls.nil? || (max_calls.is_a?(Integer) && max_calls.positive?)
+
+        raise ArgumentError, 'max_calls must be a positive integer'
+      end
+
+      def perform(reservation, coworker)
+        return reservation if reservation.is_a?(Hash)
+
+        index, full_prompt = reservation
+        execute_call(index, full_prompt, coworker)
+      rescue StandardError => e
+        complete(index, error: "Coworker '#{coworker}' failed: #{e.message}")
+      rescue Exception => e # rubocop:disable Lint/RescueException -- finalize the call, then propagate
+        complete(index, error: "Coworker '#{coworker}' crashed: #{e.class}: #{e.message}")
+        raise
+      end
+
+      def execute_call(index, full_prompt, coworker)
+        role = coworker.to_s
+        return complete(index, error: unknown_coworker(coworker)) unless @agents.key?(role)
+
+        result = ask_agent(@agents.fetch(role), role, full_prompt)
+        complete(index, result: extract_result(result), usage: usage_from(result))
+      end
+
+      # Best-known token accounting; absent metering is reported as nil, never guessed.
+      def usage_from(raw)
+        return unless raw.respond_to?(:input_tokens)
+
+        usage = { input_tokens: raw.input_tokens, output_tokens: raw.output_tokens }
+        usage[:model_id] = raw.model_id if raw.respond_to?(:model_id)
+        usage = usage.compact
+        usage.empty? ? nil : usage
+      end
+
+      def unknown_coworker(coworker)
+        "Unknown coworker '#{coworker}'. Available: #{coworkers}"
+      end
+
+      def reserve(action, coworker, prompt, as:, from:)
+        @mutex.synchronize { reserve_call(action, coworker, prompt, artifact_name: as, artifacts: from) }
+      end
+
+      def reserve_batch(tasks, from)
+        @mutex.synchronize do
+          tasks.map do |coworker, prompt|
+            role = coworker.to_s
+            [coworker, reserve_call('delegate_work', role, prompt, artifact_name: role, artifacts: from)]
+          end
+        end
+      end
+
+      def reserve_call(action, coworker, prompt, artifact_name:, artifacts:)
+        artifact_name = normalize_artifact_name(artifact_name)
+        return reject_call(action, coworker, prompt, artifact_name) if call_limit_reached?
+
+        prior_calls, inputs = handoff_context(artifacts)
+        @accepted_calls += 1
+        full_prompt = with_history(prompt, prior_calls.map(&:last))
+        [append_running_call(action, coworker, full_prompt, inputs, artifact_name), full_prompt]
+      end
+
+      def append_running_call(action, coworker, full_prompt, inputs, artifact_name)
+        index = @calls.length
+        @reserved_versions[index] = (@artifact_serials[artifact_name] += 1) if artifact_name
+        @calls << build_call(
+          action, coworker, full_prompt, nil, status: :running, inputs: inputs, artifact: artifact_name
+        )
+        index
+      end
+
+      # Versions are reserved here in submission order, so +artifact(name)+ stays
+      # deterministic when parallel work completes out of order. A failed call
+      # leaves a visible gap instead of renumbering published versions.
+      def handoff_context(artifact_names)
+        return context_calls(artifact_names) if @share_context
+
+        if artifact_names && !Array(artifact_names).empty?
+          raise ArgumentError, 'from: requires a session that shares context'
+        end
+
+        [[], []]
+      end
+
+      def call_limit_reached? = @max_calls && @accepted_calls >= @max_calls
+
+      # Names the budget and the blocked coworker so a hand-counted max_calls
+      # is diagnosable from the error alone.
+      def reject_call(action, coworker, prompt, artifact_name)
+        message = "#{BUDGET_MESSAGE}: #{@accepted_calls} of #{@max_calls} calls used, " \
+                  "'#{coworker}' was not run"
+        append_call(action, coworker, prompt, error: message, artifact: artifact_name)
+          .merge(budget_exceeded: true)
+      end
+
+      def context_calls(artifact_names)
+        return artifact_context(artifact_names) unless artifact_names.nil?
+
+        selected_artifact_context(@artifacts.values.filter_map(&:last).sort_by(&:call_index))
+      end
+
+      def artifact_context(names)
+        selected = Array(names).map do |name|
+          artifact = @artifacts.fetch(name.to_s, []).last
+          raise ArgumentError, "No completed artifact named '#{name}'" unless artifact
+
+          artifact
+        end
+        selected_artifact_context(selected)
+      end
+
+      def selected_artifact_context(selected)
+        calls = selected.map { |item| [item.call_index, @calls.fetch(item.call_index)] }
+        inputs = selected.map { |item| "#{item.name}@v#{item.version} (#{item.producer})" }
+        [calls, inputs]
+      end
+
+      def normalize_artifact_name(name)
+        return if name.nil?
+
+        value = name.to_s
+        raise ArgumentError, 'provide an artifact name' if value.empty?
+
+        value.freeze
+      end
+
+      def with_history(prompt, calls)
+        full_prompt = @context ? "#{prompt}\n\nShared team context:\n#{@context}" : prompt
+        return full_prompt unless @share_context
+
+        history = calls.map { |call| fenced_result(call) }.join("\n\n")
+        return full_prompt if history.empty?
+
+        "#{full_prompt}\n\nPrevious coworker results (verbatim):\n#{history}"
+      end
+
+      # Each result is wrapped in a per-session random fence. A coworker cannot guess the
+      # nonce, so relayed output cannot impersonate a handoff from a coworker that never ran.
+      def fenced_result(call)
+        "--- result #{@fence} #{call.coworker} via #{call.action} ---\n" \
+          "#{format_result(call.result)}\n" \
+          "--- end #{@fence} ---"
+      end
+
+      # Re-entrancy is a property of the role, not of how it was registered: a class-backed
+      # coworker gets a fresh instance per call and so never touches the mutex below.
+      def ask_agent(agent, role, prompt)
+        if active_roles.include?(role)
+          raise CollaborationError, "Coworker '#{role}' cannot be consulted from inside its own call"
+        end
+
+        active_roles << role
+        begin
+          call_agent(agent, role, prompt)
+        ensure
+          active_roles.delete(role)
+        end
+      end
+
+      def call_agent(agent, role, prompt)
+        return agent.new.ask(prompt) if agent.is_a?(Class)
+
+        @agent_mutexes.fetch(role).synchronize { agent.ask(prompt) }
+      end
+
+      # Fiber-local, so concurrent work on the same role stays legal while a nested call
+      # inside one fiber or thread is refused.
+      def active_roles
+        Thread.current[:"ruby_llm_team_active_#{object_id}"] ||= []
+      end
+
+      def parallel_runner(concurrency)
+        return :parallel_with_threads if concurrency.to_sym == :threads
+
+        if concurrency.to_sym == :fibers
+          require 'async'
+          return :parallel_with_fibers
+        end
+
+        raise ArgumentError, 'concurrency must be :threads or :fibers'
+      rescue LoadError
+        raise LoadError, "The 'async' gem is required for fiber concurrency"
+      end
+
+      def parallel_with_threads(work)
+        workers = work.map do |coworker, reservation|
+          [coworker, Thread.new { perform(reservation, coworker) }]
+        end
+        workers.to_h { |coworker, worker| [coworker, worker.value] }
+      ensure
+        workers&.each { |pair| join_quietly(pair.last) }
+      end
+
+      # The first crash already propagates through Thread#value; joining the rest
+      # must not mask it with a sibling's exception.
+      def join_quietly(worker)
+        worker.join
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+
+      def parallel_with_fibers(work)
+        Async do |parent|
+          workers = work.to_h do |coworker, reservation|
+            [coworker, parent.async { crash_as_value(reservation, coworker) }]
+          end
+          settle_fibers(workers)
+        end.wait
+      end
+
+      # Async starts tasks eagerly, so a crash escaping the block would abort
+      # sibling task creation; carry it as a value and raise after settling.
+      def crash_as_value(reservation, coworker)
+        perform(reservation, coworker)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        e
+      end
+
+      # Waits for every task before propagating the first crash, so a sibling
+      # is never cancelled with its call still recorded as :running.
+      def settle_fibers(workers)
+        outcomes = workers.transform_values(&:wait)
+        crash = outcomes.each_value.find { |value| value.is_a?(Exception) }
+        raise crash if crash
+
+        outcomes
+      end
+
+      def complete(index, result: nil, error: nil, usage: nil)
+        @mutex.synchronize do
+          call = @calls.fetch(index)
+          completed, result = completed_call(call, result, error, usage)
+          @calls[index] = completed
+          publish_artifact(completed, index) if completed.successful? && completed.artifact
+          result
+        end
+      end
+
+      def completed_call(call, result, error, usage)
+        result = { error: error } if error
+        status = error ? :failed : :completed
+        completed = build_call(
+          call.action, call.coworker, call.prompt, result,
+          status: status, inputs: call.inputs, artifact: call.artifact, usage: usage
+        )
+        [completed, result]
+      end
+
+      def publish_artifact(call, index)
+        versions = @artifacts.fetch(call.artifact, [])
+        artifact = Artifact.new(
+          name: call.artifact,
+          version: @reserved_versions.fetch(index),
+          producer: call.coworker,
+          sources: call.inputs,
+          value: call.result,
+          call_index: index
+        ).freeze
+        @artifacts[call.artifact] = [*versions, artifact].sort_by(&:version).freeze
+      end
+
+      def append_call(action, coworker, prompt, error:, artifact: nil)
+        result = { error: error }
+        @calls << build_call(action, coworker, prompt, result, status: :failed, inputs: [], artifact: artifact)
+        result
+      end
+
+      def build_call(action, coworker, prompt, result, details)
+        Call.new(
+          action: action,
+          coworker: coworker,
+          prompt: prompt.to_s.dup.freeze,
+          result: immutable(result),
+          status: details.fetch(:status),
+          inputs: immutable(details.fetch(:inputs)),
+          artifact: details.fetch(:artifact),
+          usage: immutable(details[:usage])
+        ).freeze
+      end
+
+      def immutable(value)
+        case value
+        when Hash then value.to_h { |key, item| [immutable(key), immutable(item)] }.freeze
+        when Array then value.map { |item| immutable(item) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
+      end
+
+      def call_to_h(call, index, include_content)
+        serialized = {
+          index: index, action: call.action, coworker: call.coworker,
+          status: call.status, artifact: call.artifact, inputs: call.inputs, usage: call.usage
+        }
+        # The exported prompt is the exact text the coworker received, context and
+        # handoffs included — the readable Markdown trace is where it is trimmed.
+        serialized.merge!(prompt: call.prompt, result: call.result) if include_content
+        serialized
+      end
+
+      def usage_totals(snapshot)
+        metered = snapshot.filter_map(&:usage)
+        return if metered.empty?
+
+        {
+          input_tokens: metered.sum { |usage| usage[:input_tokens].to_i },
+          output_tokens: metered.sum { |usage| usage[:output_tokens].to_i }
+        }
+      end
+
+      # Callers hold @mutex.
+      def artifacts_to_h
+        @artifacts.transform_values do |versions|
+          versions.map do |artifact|
+            { version: artifact.version, producer: artifact.producer,
+              call_index: artifact.call_index, sources: artifact.sources }
+          end
+        end
+      end
+
+      def extract_result(result)
+        return result unless result.respond_to?(:content)
+
+        content = result.content
+        if content.respond_to?(:text) && content.respond_to?(:attachments)
+          attachments = Array(content.attachments)
+          content = content.text
+        else
+          attachments = result.respond_to?(:attachments) ? Array(result.attachments) : []
+        end
+        attachments.empty? ? content : [content, *attachments]
+      end
+
+      def format_result(result)
+        result.is_a?(Hash) ? JSON.pretty_generate(result) : result.to_s
+      end
+    end # rubocop:enable Metrics/ClassLength
+
+    class CoworkerTool < Tool # :nodoc:
+      def self.declare_shared_params
+        param :coworker, type: 'string', description: 'Name of the coworker to consult'
+        param :context, type: 'string', description: 'Shared context for the coworker',
+                        required: false
+      end
+
+      def initialize(session)
+        super()
+        @session = session
+      end
+
+      def description
+        "#{self.class.description}\n\nCoworkers: #{@session.coworkers}"
+      end
+
+      private
+
+      def with_context(main, context)
+        context ? "#{main}\n\nContext: #{context}" : main
+      end
+
+      def consult(action:, prompt:, coworker:)
+        @session.consult(action: action, prompt: prompt, coworker: coworker)
+      end
+    end
+
+    class DelegateWork < CoworkerTool # :nodoc:
+      description 'Delegate a task to a coworker and get their result'
+      declare_shared_params
+      param :task, type: 'string', description: 'The task to delegate'
+
+      def name = 'delegate_work'
+
+      def execute(task:, coworker:, context: nil)
+        consult(action: name, prompt: with_context(task, context), coworker: coworker)
+      end
+    end
+
+    class AskQuestion < CoworkerTool # :nodoc:
+      description 'Ask a coworker a question about their expertise'
+      declare_shared_params
+      param :question, type: 'string', description: 'The question to ask'
+
+      def name = 'ask_question'
+
+      def execute(question:, coworker:, context: nil)
+        consult(action: name, prompt: with_context(question, context), coworker: coworker)
+      end
+    end
+
+    private_constant :CoworkerTool, :DelegateWork, :AskQuestion
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-team
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JetThoughts
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.16.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.16.0
+description: 'A RubyLLM extension that groups named coworkers and exposes delegation
+  tools so a model can hand tasks and questions to teammates. Built on the RubyLLM
+  public API: Tool, Agent, Message, and Attachment.'
+email:
+- team@jetthoughts.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ruby_llm/team.rb
+- lib/ruby_llm/team/artifact.rb
+- lib/ruby_llm/team/run.rb
+- lib/ruby_llm/team/version.rb
+homepage: https://github.com/jetthoughts/ruby_llm-team
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jetthoughts/ruby_llm-team
+  source_code_uri: https://github.com/jetthoughts/ruby_llm-team
+  changelog_uri: https://github.com/jetthoughts/ruby_llm-team/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: 'Team collaboration for RubyLLM: delegate work to named coworkers.'
+test_files: []