little_ghost 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9890ec252b435a45ce78f82a57b107fbfa7f1846f4cf580e0538ce3303c2d7c5
-  data.tar.gz: 47c8aa6beeaf56a8987088007fa67e56144394a3fff1dcdb8e357812725ab7e6
+  metadata.gz: c6ec454a6085af7b0e2519eb0137e2f70115f0c00197d9f1914ac336c9fe4810
+  data.tar.gz: bde8feed25fc76a6e0290ec8462b12eb5b2df90c368214850caaa705a3da75d2
 SHA512:
-  metadata.gz: 92540329eaa105782f108dc52cf0e21351b7ae60c674d6b6d786a460b221e54f569ae7f3240bdb0d8a436ea6b0102ef1d14251fa543d2d9c7522aad6d9142f4a
-  data.tar.gz: 3dcb8b76e48448cbbd8088cfc0ee5ef0edcfcdb4b595c93ed741d60ee9f852a4ece504794119bdd874761ed1e40af97f7e05f6bb3f81884c9b8d4c4b0656a43a
+  metadata.gz: 0c7081dc35068d5e3e3e0d917e4f024657cbecc117a0952b4ccfa329a9a4be2de77a96c87d9d7cf1eb3f9092219ed108d07422fa501e427542fdfb400aaf3e4a
+  data.tar.gz: 939d5fac29d8a1607225185f09784e2fe014d7ef20c20ba856ebda0b30c8e6634a79a9ff94725287f924576caecb2080204dec5fa7b36af3b801d02c3d9de93c

data/README.md

@@ -1,18 +1,54 @@
-# Build AI features with LittleGhost
+# Build AI features that feel at home in Ruby
 
-<hr>
+> **Using a coding agent?** Start with
+> [`llms.txt`](https://mattyr.github.io/little_ghost/llms.txt) for a concise map
+> of the guides and API. [`llms-full.txt`](https://mattyr.github.io/little_ghost/llms-full.txt)
+> contains the complete documentation in one file.
 
-**Growing in public.** LittleGhost is under active development, and interfaces may evolve between releases. Pin the gem version and review the release notes when upgrading.
+LittleGhost is a Ruby library for building AI features with agents and composable assemblies. With `OPENROUTER_API_KEY` set, start with one class, give it a prompt, and call it like the rest of your application code:
 
-<hr>
+```ruby
+require "little_ghost"
+
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Answer customer questions clearly and concisely."
+end
+
+run = CustomerSupportAgent.ask("Draft a friendly greeting for a customer.")
+run.response
+# One possible response: Hi! How can I help today?
+```
+
+That small definition is already a complete agent. LittleGhost makes the model call, tracks usage, supports streaming, and closes the resources it creates for the request. Add a tool when the agent needs something from your application. Bring in more agents when the work grows.
+
+Model requests may send system instructions, caller input, conversation history,
+Tool results, and attachments to the selected provider. Model wording can vary
+between runs. [Models and Providers](docs/guides/models_and_providers.md) explains
+how to choose where each Agent sends its requests.
 
-Build an agent inside an existing Ruby system, or use LittleGhost as the core of a dedicated AI service. An agent is a reusable Ruby class that gives one model a prompt, tools, limits, and a model selection. LittleGhost connects that class to providers, streaming, sessions, delegation, and observability.
+## Install the gem
 
-Set `OPENAI_API_KEY`, then paste this customer support agent into a Ruby console or file. It selects a model directly and exposes one validated application tool:
+LittleGhost requires Ruby 3.3 or newer. Add it to your bundle and provide a provider credential:
 
 ```ruby
-require "little_ghost"
+gem "little_ghost"
+```
 
+```sh
+$ bundle install
+$ export OPENROUTER_API_KEY="..."
+```
+
+OpenRouter keeps the first setup to one credential. It is not required: LittleGhost also includes adapters for OpenAI-compatible APIs, Anthropic, Gemini, Vertex AI, and Bedrock. [Running in Production](docs/guides/production.md) shows how to configure providers and give model choices application-facing names.
+
+LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI, or service. If you want a conventional layout, start with `app/agents`, `app/assemblies`, `app/prompts`, and `app/tools`.
+
+## Give an agent real capabilities
+
+Tools let an agent call focused parts of your application:
+
+```ruby
 class HelpCenterLookupTool < LittleGhost::Tool
   description "Look up a help center entry by topic."
   input_schema(
@@ -29,39 +65,39 @@ class HelpCenterLookupTool < LittleGhost::Tool
 end
 
 class CustomerSupportAgent < LittleGhost::Agent
-  description "Answers customer support questions."
-  model "openai:gpt-5.6-luna"
-  system_prompt "Answer clearly. Check the help center before stating company guidance."
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Check the help center before stating company guidance."
   tools HelpCenterLookupTool
 end
-
-run = CustomerSupportAgent.ask("Can I get a refund after two weeks?")
-puts run.response
-# One possible response:
-# Refunds are available within 30 days, so your purchase is eligible.
 ```
 
-The completed `LittleGhost::Run` exposes its outcome, final response, normalized messages, token usage, and terminal error. Streaming callers receive `LittleGhost::StreamEvent` objects instead of provider-specific payloads:
+The schema checks the shape of the input. Your Ruby code still decides whether
+the operation is allowed. The result goes back to the model as context.
 
-```ruby
-CustomerSupportAgent.stream_ask("Can I get a refund?").each do |event|
-  print event.data.fetch(:text) if event.type == :text_delta
-end
-```
+An ordinary Tool runs in your Ruby process. When a Tool needs files or child
+processes, it can delegate that work through a Sandbox. Code mode goes one step
+further: a sandboxed interpreter can compose several Tools, while every Tool
+call still returns to your Ruby Tool for validation and permission checks.
 
-## How the pieces fit
+## Grow without changing the caller
 
-One agent is the smallest useful LittleGhost application. A request creates a run, the agent may call a tool or delegate to a subagent, and the run records the outcome:
+An **agent** owns one model loop. An **assembly** is one or more agents working as a unit. You call either one the same way:
 
-```text
-provider connections + model selections ──> ModelResolver ──> provider
-                                               │
-request ──> CustomerSupportAgent ──> HelpCenterLookupTool
-                  │
-                  └────────> ResearchAgent subagent
+```ruby
+CustomerSupportAgent.ask(question)
+ResponseWorkflow.ask(question)
+ProblemSolverSwarm.ask(question)
+SupportFlowGraph.ask(question)
 ```
 
-When one model loop is not enough, LittleGhost calls the larger callable unit an **assembly**. An assembly may be one agent or a coordinated group that still looks like one agent to its caller:
+Choose the coordination style that matches who should control the next step:
+
+- A **subagent** lets a model delegate an addressable task.
+- A **workflow** uses ordinary Ruby for ordering and branching.
+- A **swarm** lets configured agents choose permitted handoffs.
+- A **graph** makes allowed routes explicit as nodes and edges.
+
+A Workflow or Graph can contain agents, other assemblies, or both. Named classes are the clearest place to begin. Builders are there when your application discovers the participants or routes at runtime.
 
 ```text
 request ──> CustomerSupportAgent
@@ -73,67 +109,37 @@ request ──> ProblemSolverSwarm ──> TriageAgent ──handoff──> Bill
 request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseAgent
 ```
 
-A `Workflow` uses ordinary Ruby to enforce ordering and branching. A `Swarm` lets configured agents hand the request directly to one another. A `Graph` follows application-declared nodes and edges when the allowed paths should be visible in advance. These types share `ask` and `stream_ask`, so callers can depend on one entrypoint contract while the implementation grows.
-
-Class definitions are the default way to organize agents and assemblies. Builder objects support definitions whose participants or topology are discovered at runtime; the Core Concepts guide introduces them after the class-based forms.
-
-Each top-level execution owns one run lifecycle. The run checkpoints session state, closes its resources, aggregates usage, and emits framework events regardless of which assembly type is the entrypoint.
-
-## Installation and configuration
-
-LittleGhost requires Ruby 3.3 or newer. Add it to your bundle:
-
-```ruby
-gem "little_ghost"
-```
-
-Then run `bundle install`. Built-in OpenAI-compatible, OpenRouter, Anthropic, Gemini, Vertex AI, and Amazon Bedrock integrations use Ruby's standard library and normalize responses into the same protocol.
-
-Configuration does not require a particular directory layout. Provider connections and model profiles resolve independently in this order:
-
-1. An inline `config.providers` or `config.models` declaration.
-2. The corresponding explicit `config.providers_path` or `config.models_path`.
-3. The optional conventional file under `config/little_ghost/`.
-4. Environment-based provider selection and the built-in `default` profile.
-
-An explicit path must exist. A missing conventional file is valid. The conventional form keeps connection policy separate from model roles:
-
-```yaml
-# config/little_ghost/providers.yml
-providers:
-  openai:
-    adapter: openai
-    api_key: <%= ENV.fetch("OPENAI_API_KEY") %>
-```
-
-```yaml
-# config/little_ghost/models.yml
-default_model: customer_support
-models:
-  customer_support:
-    target: openai:gpt-5.6-luna
-```
-
-By default, LittleGhost maps `default` to GPT-5.6 Luna. It configures conventional OpenRouter and OpenAI connections from nonblank `LITTLEGHOST_OPENROUTER_API_KEY`, `LITTLEGHOST_OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `OPENAI_API_KEY` values; that order determines the default when more than one provider is available. Model inputs—including prompts, history, tool data, and attachments—leave the application for the selected external provider. Configure providers explicitly when provider choice or data residency matters.
-
-Applications that need custom routing can subclass `LittleGhost::ModelResolver` and install the class with `config.model_resolver`. A custom resolver owns its profiles and default role; configuring `models`, `models_path`, or `default_model` at the same time is an error. Provider configuration remains available to the resolver.
+The result stays familiar too. Every call returns a `Run` with the response,
+outcome, usage, and any final error. A coordinated assembly also records which
+participants ran. Use `.stream_ask` to watch the work as it happens.
 
-LittleGhost runs inside the surrounding Ruby process; it does not prescribe an HTTP server, CLI, job system, or application layout. `config/little_ghost`, `app/agents`, `app/assemblies`, `app/prompts`, `app/tools`, and `app/skills` are optional conventions. Keep agent classes in `app/agents`; workflow, swarm, and graph classes conventionally live in `app/assemblies`. Names should reveal the type, such as `DevelopmentWorkflow`, `ProblemSolverSwarm`, or `SupportFlowGraph`.
+LittleGhost is pre-1.0. Pin the gem version and review release notes before
+upgrading, because interfaces may change between releases.
 
-## Documentation
+## Keep going
 
-- [Getting Started](docs/guides/getting_started.md) builds and streams the customer support example.
-- [Core Concepts](docs/guides/core_concepts.md) starts with one agent, then introduces assemblies, delegation, workflows, swarms, graphs, and dynamic builders.
-- [API reference](rdoc-ref:LittleGhost) covers exact signatures, options, and lifecycle behavior.
+- [Getting Started](docs/guides/getting_started.md) takes you from installation to a tool-backed, streaming agent.
+- [Core Concepts](docs/guides/core_concepts.md) builds the mental model from Agent to Assembly.
+- [Models and Providers](docs/guides/models_and_providers.md) gives shared model choices application-facing names.
+- [Prompts as Views](docs/guides/prompt_views.md) gives growing instructions, shared pieces, and application values a natural home.
+- [Tools](docs/guides/tools.md) explains how models call focused Ruby operations.
+- [Structured Results and Content](docs/guides/structured_outputs_and_content.md) covers checked result shapes, images, and documents.
+- [Compose Agents](docs/guides/assemblies.md) walks through workflows, swarms, graphs, nesting, and builders.
+- [Skills](docs/guides/skills.md) organizes reusable instructions and supporting resources.
+- [Workspaces and Sandboxes](docs/guides/sandboxing.md) gives files and child processes a deliberate place to run.
+- [Code Mode](docs/guides/code_mode.md) lets a model compose Tools in sandboxed Ruby or optional JavaScript.
+- [Integrations](docs/guides/integrations.md) connects MCP, AG-UI, and OpenTelemetry.
+- [Running in Production](docs/guides/production.md) covers configuration, saved conversations, supervision, and observability.
+- [API reference](rdoc-ref:LittleGhost) provides exact method signatures and ownership rules.
 
-## Contributing
+### For contributors
 
 See the [contributing guide](https://github.com/mattyr/little_ghost/blob/main/CONTRIBUTING.md), [Code of Conduct](https://github.com/mattyr/little_ghost/blob/main/CODE_OF_CONDUCT.md), and [security policy](https://github.com/mattyr/little_ghost/blob/main/SECURITY.md).
 
 ```sh
-bundle install
-bundle exec rake test
-bundle exec standardrb --no-fix
+$ bundle install
+$ bundle exec rake test
+$ bundle exec standardrb --no-fix
 ```
 
-LittleGhost is licensed under the MIT License.
+LittleGhost is available under the MIT License.

data/docs/guides/assemblies.md

@@ -0,0 +1,412 @@
+# Compose Agents
+
+An Assembly lets several participants answer through the same familiar calls as one Agent. This guide grows the customer-support example through each coordination style, then shows how to nest and construct assemblies dynamically.
+
+## Call every assembly the same way
+
+Callers do not need a branch for each implementation:
+
+```ruby
+entrypoint = urgent? ? EscalationWorkflow : CustomerSupportAgent
+run = entrypoint.ask(question)
+```
+
+`Agent`, `Workflow`, `Swarm`, and `Graph` all answer through the Assembly calling style. They differ in how they coordinate work, not in how your application calls them.
+
+## Use a Workflow for explicit application logic
+
+A Workflow's `perform` method is ordinary Ruby. Inside it, `invoke` prepares a child call. Read `.output` when you need an intermediate answer. Return the final `invoke` call untouched so its response can stream to the caller.
+
+```ruby
+class ResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    research = invoke(ResearchAgent).output
+
+    invoke CustomerSupportAgent, input: <<~PROMPT
+      #{input.text}
+
+      Verified research:
+      #{research}
+    PROMPT
+  end
+end
+
+run = ResponseWorkflow.ask("Why is transfer 481 pending?")
+run.response
+```
+
+Every participant passed to `invoke` can be an Agent or another Assembly. By default, each child receives the caller's history and application context. Pass `history: []`, `context: {}`, or redacted values when a child should see less.
+
+Each child Agent keeps its own [prompt view](prompt_views.md). The Workflow supplies request-specific input; it does not replace that Agent's reusable system instructions.
+
+The last child is special because its events become the Workflow's public stream. Return that `invoke` without consuming it:
+
+```ruby
+# Wrong: this returns a String after consuming the final invocation.
+def perform
+  invoke(CustomerSupportAgent).output
+end
+
+# Right: this returns the lazy invocation itself.
+def perform
+  invoke CustomerSupportAgent
+end
+```
+
+The first version produces a failed top-level Run whose error is `ProtocolError`. Use `.output` only when Ruby needs an intermediate answer before choosing the next step.
+
+### Choose a branch in Ruby
+
+Each branch should end with its final unconsumed invocation:
+
+```ruby
+class RoutedResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    route = invoke(TriageAgent, as: :triage).output
+
+    if route == "billing"
+      invoke BillingAgent, as: :billing_response
+    else
+      invoke CustomerSupportAgent, as: :general_response
+    end
+  end
+end
+```
+
+`as:` gives the child a readable participant name in steps, trajectories, and telemetry. It does not change which Assembly runs.
+
+### Run independent work in parallel
+
+Use `parallel` when several inputs can be processed independently:
+
+```ruby
+class InvestigationWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    findings = parallel(
+      invoke(LedgerResearchAgent),
+      invoke(PolicyResearchAgent),
+      max_concurrency: 2
+    )
+
+    invoke CustomerSupportAgent, input: <<~PROMPT
+      #{input.text}
+
+      Findings:
+      #{findings.join("\n")}
+    PROMPT
+  end
+end
+```
+
+`max_concurrency` limits how many calls run at once. Each one gets its own copy of the workflow context. Cancellation still depends on the provider or tool noticing its token or deadline.
+
+## Use a Swarm for specialist handoffs
+
+A Swarm keeps one Agent active at a time. You decide which specialists it may hand work to:
+
+```ruby
+class ProblemSolverSwarm < LittleGhost::Swarm
+  member TriageAgent
+  member BillingAgent
+  member AccountAgent
+
+  start TriageAgent
+  handoff TriageAgent, to: [BillingAgent, AccountAgent]
+  handoff BillingAgent, to: TriageAgent
+  handoff AccountAgent, to: TriageAgent
+
+  max_steps 10
+  max_handoff_repeats 2
+end
+```
+
+The active model sees a handoff tool listing the members it may choose next. LittleGhost accepts only the routes you declared. `max_steps` limits total member executions. `max_handoff_repeats` limits how often the same directed handoff, such as triage to billing, may repeat.
+
+Swarm members must be Agents, so each transition stays a direct model-to-model handoff. Caller history and application context are opt-in for each member. Handoff messages come from a model; never treat them as permission to read data or perform an action.
+
+Opt in only for a member that needs the data:
+
+```ruby
+member AccountAgent, history: true, context: true
+```
+
+Intermediate model text stays out of the caller-facing stream, leaving one
+coherent public answer. The next member still receives the handoff, and the
+result keeps a bounded summary of the journey.
+
+## Use a Graph for guided routes
+
+A Graph names the possible stops and the routes between them. Start with a conditional route before adding parallel branches:
+
+```ruby
+class SupportFlowGraph < LittleGhost::Graph
+  node :triage, TriageAgent
+  node :billing, BillingAgent
+  node :general, CustomerSupportAgent
+  node :respond, CustomerSupportAgent
+
+  start :triage
+
+  edge :triage, :billing do |state|
+    state.result(:triage).output == "billing"
+  end
+  edge :triage, :general
+  edge :billing, :respond
+  edge :general, :respond
+  finish :respond
+end
+
+SupportFlowGraph.validate!
+```
+
+Conditions and input mappers read an immutable `Graph::State`. At most one conditional route may match. If several match, LittleGhost raises `AssemblyRoutingError` instead of guessing which one wins. One unconditional edge can catch the request when none match.
+
+Graph nodes start without caller history or application context. The start node receives the original input. By default, each downstream node receives the original task plus its immediate predecessor results. Use an input mapper to replace or redact that data before it moves to a provider or participant that should see less.
+
+Opt in when a node needs caller context:
+
+```ruby
+node :account_lookup, AccountLookupAgent, context: true
+```
+
+### Run bounded parallel paths
+
+Give one node several unconditional edges when its result should start independent branches. LittleGhost finds their first unambiguous common successor and waits for every branch before running it:
+
+```ruby
+class InvestigationGraph < LittleGhost::Graph
+  node :triage, TriageAgent
+  node :ledger, LedgerResearchAgent
+  node :policy, PolicyResearchAgent
+  node :respond, CustomerSupportAgent
+
+  start :triage
+  edge :triage, :ledger
+  edge :triage, :policy
+  edge :ledger, :respond
+  edge :policy, :respond
+  finish :respond
+end
+```
+
+Set `max_concurrency` on the Graph to bound every parallel group. An edge with
+an array target can declare the group explicitly and override that bound:
+
+```ruby
+max_concurrency 4
+edge :triage, [:ledger, :policy], max_concurrency: 2
+edge [:ledger, :policy], :respond
+```
+
+#### Join parallel branches
+
+An array source declares a wait-for-all convergence. Use it when the common
+successor cannot be inferred or when the convergence needs its own input
+mapper. Parallel groups cannot nest. `validate!` raises `ConfigurationError`
+when inference has no single convergence, finds competing routes at a branch
+boundary, or encounters overlapping or nested groups.
+
+The first nodes in a parallel group receive the original task and the source
+result. The convergence target receives the original task and each immediate
+predecessor result in declaration order. LittleGhost labels them as context:
+
+```text
+Original Task:
+Why is transfer 481 pending?
+
+Inputs from previous nodes:
+
+From ledger:
+The ledger entry is awaiting settlement.
+
+From policy:
+Pending transfers usually settle within two business days.
+```
+
+#### Map inputs between nodes
+
+An `input` mapper replaces this default with the exact value returned by the
+mapper. Put it on an edge to control one transition, or on a node to control
+every route into that target. A selected edge or edge-group mapper takes
+precedence over the target node mapper:
+
+```ruby
+edge :triage, :ledger, input: lambda { |state|
+  "Investigate this transfer:\n#{state.result(:triage).output}"
+}
+```
+
+Conditions and mappers receive a copied, frozen `Graph::State`, so they cannot
+change the running Graph.
+Use `state.input` for the original request, `state.results` for completed nodes,
+and `state.incoming_results` for the immediate predecessors. The
+`LittleGhost::Graph::State` API reference lists every routing value.
+
+Conditions and mappers are application code. Their state includes copies of
+caller history and application context, even when the destination node does not
+receive those values.
+
+Use an explicit array-source edge when a fan-in needs one mapper:
+
+```ruby
+edge [:ledger, :policy], :respond, input: lambda { |state|
+  JSON.generate(state.incoming_results.transform_values(&:output))
+}
+```
+
+#### Control data crossing branches
+
+By default, the original request and complete source output go to every
+parallel branch. An input mapper can replace the branch input, and a redaction
+assembly before the fan-out can narrow the source output. Use those options
+when a participant or provider should receive only part of the data.
+
+#### Recover and review
+
+An error edge can send an expected failure to a recovery Assembly. Call `validate!` before the first run.
+
+Once the topology grows, `InvestigationGraph.to_mermaid` returns Mermaid diagram source for the routes you declared. Render it in a Mermaid-aware editor or documentation page when a picture makes the graph easier to review.
+
+## Make retries safe
+
+Workflow calls, Swarm members, and Graph nodes can set timeouts and retries. Use them for work that can safely be attempted again:
+
+```ruby
+invoke(
+  ResearchAgent,
+  timeout: 15,
+  retries: 2,
+  retry_on: [LittleGhost::ProviderError],
+  retry_delay: 0.25
+)
+```
+
+A timeout asks the running code to stop; it cannot forcibly end arbitrary Ruby or provider work. A retry repeats the whole child step. Retry only selected failures, and make sure repeated external actions are safe.
+
+Retries start at zero. When `retries` is greater than zero, `retry_on` must list the exception classes that are safe to try again. LittleGhost does not retry every failure by default.
+
+## Watch every agent in an assembly
+
+Follow each participant while a composite assembly runs by handling its contextual `:agent_stream` events. These events arrive alongside the coherent public answer and assembly lifecycle events:
+
+```ruby
+stream = SupportFlowGraph.stream_ask("Why was I charged twice?")
+
+run = stream.each do |event|
+  next unless event.type == :agent_stream
+
+  source = event.data.fetch(:source)
+  agent_event = event.data.fetch(:event)
+  participant = source.assembly_path.last&.participant || source.agent_id
+
+  case agent_event.type
+  when :invocation_start
+    routed_input = event.data.fetch(:input)
+    render_input(participant, routed_input)
+  when :text_delta
+    publish_progress(participant, agent_event.data.fetch(:text))
+  when :invocation_stop
+    record_result(participant, agent_event.data.fetch(:result))
+  end
+end
+
+run.completed? # => true
+```
+
+`source.agent_id` identifies the Agent class, `source.agent_path` distinguishes managed subagents, and `source.operation_id` groups one invocation. `source.assembly_path` lists the enclosing Workflow, Swarm, or Graph steps from the outside inward.
+
+The routed input and inner event are copied and frozen before they reach the
+observer, so changing an event can't affect the running assembly. Parallel
+participants can interleave. Events from each Agent retain their order, and
+LittleGhost never calls the stream block concurrently.
+
+The contextual wrapper arrives before the corresponding ordinary event. An assembly's final Agent therefore appears through both projections. Filter for `:agent_stream` when building an all-agent view, or handle ordinary events when rendering only the final answer. Pass `include_agent_events: false` when a composite assembly caller only wants the ordinary public stream. Standalone Agent streams keep their ordinary events by default and accept `include_agent_events: true` when source metadata is useful.
+
+The AG-UI adapter ignores contextual wrappers. Translate them explicitly if an AG-UI client should receive participant activity.
+
+> **Safety note:** A composite stream can include inputs, reasoning, Tool
+> arguments and results, errors, and output from every participant. Check that
+> the destination may see the complete Run, or filter the events before sending
+> or storing them.
+
+## Inspect what the assembly did
+
+A composite result remembers the steps it took. `trajectory` lets you explore them:
+
+```ruby
+run = InvestigationGraph.ask("Why is transfer 481 pending?")
+trajectory = run.result.trajectory
+
+trajectory.each { |step| puts "#{step.participant}: #{step.status}" }
+trajectory.transitions
+ledger = trajectory.find { |step| step.participant == "ledger" }
+policy = trajectory.find { |step| step.participant == "policy" }
+trajectory.concurrent?(ledger.id, policy.id)
+```
+
+Step outputs and buffered events have size limits. Use your application's
+instrumentation when you need deeper diagnostics.
+
+## Compose assemblies inside assemblies
+
+Workflow and Graph participants accept any Assembly definition:
+
+```ruby
+class ResolutionGraph < LittleGhost::Graph
+  node :investigate, InvestigationWorkflow
+  node :resolve, ProblemSolverSwarm
+
+  start :investigate
+  edge :investigate, :resolve
+  finish :resolve
+end
+```
+
+An Assembly can also become an Agent tool:
+
+```ruby
+class SupportCoordinatorAgent < LittleGhost::Agent
+  assembly_as_tool InvestigationGraph,
+    name: "investigate_support_request",
+    preserve_context: false
+end
+```
+
+The nested assembly receives the parent Tool's current working state. That state
+may include values restored from a Session. `preserve_context` controls
+conversation history only: when it is false, working state still passes to the
+nested assembly. A nested Tool that reads private data or performs a write
+should check values established for the current request or checked again after
+loading.
+
+## Reach for builders when definitions are dynamic
+
+Classes are the preferred form in application code. Use a builder when runtime
+configuration decides the nodes or routes:
+
+```ruby
+graph = LittleGhost::GraphBuilder.new(
+  id: "support_flow",
+  description: "Routes customer support requests"
+)
+
+graph.node :triage, TriageAgent
+graph.node :respond, CustomerSupportAgent
+graph.start :triage
+graph.edge :triage, :respond
+graph.finish :respond
+graph.validate!
+
+run = graph.ask("Where is my order?")
+```
+
+Each builder uses the same declarations as its matching class. The builder stays editable, but each run gets a fixed copy of its current definition. Later edits affect later runs. Ruby callbacks still see any application objects they captured.
+
+Continue with [Skills](skills.md) when an Agent should discover focused
+instructions and supporting resources only when a task needs them.