little_ghost 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 271908b0fc40900504fb25cd57d2cbcc8d987ac1ab32a0db58353562793446fc
-  data.tar.gz: 507e5d747e8b341dd60b1edce8811e0dc5b2d41f98cb970e801284b2a326a49f
+  metadata.gz: 50e597abbf025721200897c852c8ea72e244c0b5bb2f1b50aa58084e55d5d0df
+  data.tar.gz: be4d63e81003723c9a916a61359ae508a8d35a16a02b8c7e11f14dc5a3bcd12b
 SHA512:
-  metadata.gz: 830edf81e2d4892e7b72def07ba1d1be85843c8abf5cbb25d744ad520e8586fe9de2ae1cb32084ce832bb1eb866f4fa083af95b93e59df2b3e2c47f4e5c7aea9
-  data.tar.gz: a8dba3d880bdc6adc4271daac984f9ab6384d34520a5be2071e66d1d746f4979952c13e7743364e2de2f2c2aa721057e12e54ca29c83a382b6506e49889ee43e
+  metadata.gz: f546cd196e43eb53f6e3ab812c362a9bfb5d81e5408b0608c14ba20ca865a77196c6a801ed3b8980f38e098b6e468555dc2520ee32d9ee72373b4307686b9768
+  data.tar.gz: 18294764bb5ada766b993993172cccef4e077bf7d2cb886e7f76f1a3bda7ce60a8c448547b056f55eadd2775761457f8a725d3ab895d268f9785cdc2eebac22b

data/README.md

@@ -1,11 +1,16 @@
 # Build AI features that feel at home in Ruby
 
+LittleGhost is a Ruby library for adding AI features to an existing application
+or building a dedicated AI service. An **agent** combines a model with
+instructions and Ruby operations it can call. Agents can work together in an
+**assembly**, which your application calls like a single agent.
+
 > **Using a coding agent?** Start with
 > [`llms.txt`](https://littleghostai.org/llms.txt) for a concise map
 > of the guides and API. [`llms-full.txt`](https://littleghostai.org/llms-full.txt)
 > contains the complete documentation in one file.
 
-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:
+With the gem installed and `OPENROUTER_API_KEY` set, start with one class:
 
 ```ruby
 require "little_ghost"
@@ -100,14 +105,13 @@ end
 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.
 
-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.
+An ordinary Tool runs in your Ruby process. For operations that need files or
+child processes, see [Workspaces and Sandboxes](docs/guides/sandboxing.md).
 
 ## Grow without changing the caller
 
-An **agent** owns one model loop. An **assembly** is one or more agents working as a unit. You call either one the same way:
+When a task needs several agents, choose how they work together. These example
+classes use different coordination styles, but their callers all use `.ask`:
 
 ```ruby
 CustomerSupportAgent.ask(question)
@@ -118,12 +122,12 @@ SupportFlowGraph.ask(question)
 
 Choose the coordination style that matches who should control the next step:
 
-- A **subagent** lets a model delegate an addressable task.
+- A **subagent** is a specialist an agent can ask for help.
 - 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.
+A Workflow or Graph can contain agents, other assemblies, or both.
 
 ```text
 request ──> CustomerSupportAgent
@@ -137,7 +141,9 @@ request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseA
 
 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.
+participants ran. Use `.stream_ask` to watch the work as it happens and choose
+which participants to display. [Getting Started](docs/guides/getting_started.md)
+shows how to stream an Agent's answer and read the completed result.
 
 LittleGhost is pre-1.0. Pin the gem version and review release notes before
 upgrading, because interfaces may change between releases.

data/docs/guides/assemblies.md

@@ -15,7 +15,12 @@ run = entrypoint.ask(question)
 
 ## 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, or return a value that Ruby computes from the intermediate answers.
+A Workflow's `perform` method is ordinary Ruby. Inside it, `invoke` prepares a
+child call. Read `.output` for its text or structured answer, or `.result` for
+the complete `RunResult`. Return an invocation to select its answer as the
+Workflow result. You can inspect that answer first, or return a value that Ruby
+computes from intermediate answers. Every participating Agent publishes live
+progress regardless of how you access or select results.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -41,7 +46,7 @@ Every participant passed to `invoke` can be an Agent or another Assembly. By def
 
 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 when its events should become the Workflow's public stream. Return that `invoke` without consuming it:
+When one child should supply the final answer, return its invocation:
 
 ```ruby
 def perform
@@ -49,6 +54,38 @@ def perform
 end
 ```
 
+To inspect an answer before selecting it, keep the invocation, read its output,
+and return the same invocation after your checks. For example, given a
+`ReviewAgent` whose structured result includes an `approved` boolean:
+
+```ruby
+class ReviewedResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    candidate = invoke(CustomerSupportAgent)
+    review = invoke(ReviewAgent, input: candidate.output, history: [], context: {}).output
+
+    review.fetch("approved") ? candidate : invoke(EscalationAgent)
+  end
+end
+```
+
+Returning the candidate does not repeat the work or replay its text. The final
+result preserves its conversation, state, and structured value. Usage and steps
+include both the candidate and the review. Repeated `.result` or `.output` reads
+reuse the completed result. An invocation must belong to the workflow returning
+it and must complete successfully.
+
+You can watch each Agent while the Workflow runs, including while an answer is
+being reviewed. Reviewing an answer does not hide its progress. Choose which
+participants your audience may see, as described in
+[Watch every agent](#watch-every-agent-in-an-assembly).
+
+Cancellation and deadlines apply before each child runs and before the Workflow
+returns its answer. They also apply if a checkpoint callback cancels the run or
+finishes after the deadline.
+
 When Ruby should compute the caller-visible result, consume every child and return the computed value:
 
 ```ruby
@@ -67,11 +104,11 @@ class EvidenceWorkflow < LittleGhost::Workflow
 end
 ```
 
-A returned String becomes the Workflow's textual response. Arrays, mappings, numbers, and booleans become a structured result available through `RunResult#output`, including when the Workflow is exposed with `assembly_as_tool`. Direct structured results must be JSON-compatible and stay within LittleGhost's structured-result size, depth, and complexity limits. Return an explicit value: `nil` remains a `ProtocolError`, which catches forgotten returns.
+A returned String becomes the Workflow's textual response. Arrays, mappings, numbers, and booleans become a structured result available through `RunResult#output`, including when the Workflow is exposed with `assembly_as_tool`. Computed values appear in the final result, not as synthetic text-delta events. Direct structured results must be JSON-compatible and stay within LittleGhost's structured-result size, depth, and complexity limits. Return an explicit value: `nil` remains a `ProtocolError`, which catches forgotten returns.
 
 ### Choose a branch in Ruby
 
-Each branch should end with its final unconsumed invocation or a directly computed value:
+Each branch should end with its final invocation or a directly computed value:
 
 ```ruby
 class RoutedResponseWorkflow < LittleGhost::Workflow
@@ -305,7 +342,9 @@ Retries start at zero. When `retries` is greater than zero, `retry_on` must list
 
 ## 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:
+Follow each participant by handling source-tagged `:agent_stream` events. Every
+Run uses this same progress channel, from one root Agent to nested assemblies
+and subagents. Lifecycle events and the final result remain separate:
 
 ```ruby
 stream = SupportFlowGraph.stream_ask("Why was I charged twice?")
@@ -333,19 +372,31 @@ 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.
 
+An Agent or Assembly invoked as a Tool within the Run adds a `:tool` step to that path. The
+step identifies the invoking Agent and Tool name, and its descendants retain
+the boundary. Tool-invoked Agents therefore remain distinct from the root
+Agent even when their managed-subagent path is `/root`.
+
 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.
+Agent progress appears only through `:agent_stream`, without duplicate raw
+events. Returning an invocation selects its result; it does not replay that
+Agent's progress. Handle the terminal Run event or read `run.result` for the
+complete answer and aggregate usage. Pass `include_agent_events: false` to omit
+all Agent progress without changing execution, lifecycle events, or results.
 
-The AG-UI adapter ignores contextual wrappers. Translate them explicitly if an AG-UI client should receive participant activity.
+The [AG-UI adapter](integrations.md) displays root Agent progress by default.
+Supply its `source_filter:` callable when a client should see selected assembly
+participants.
 
-> **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.
+> **Safety note:** Every Run stream can include inputs, reasoning, Tool arguments
+> and results, errors, and private output from nested participants. The example
+> above observes the complete Run. Before sending or storing events for a
+> narrower audience, select allowed sources and filter their fields. Result
+> selection does not authorize disclosure of a participant's progress.
 
 ## Inspect what the assembly did
 
@@ -362,7 +413,8 @@ 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
+The trajectory retains step outputs, not a transcript of streaming events.
+Step outputs and final results have size limits. Use your application's
 instrumentation when you need deeper diagnostics.
 
 ## Compose assemblies inside assemblies

data/docs/guides/core_concepts.md

@@ -1,6 +1,9 @@
 # Core Concepts
 
-Define an Agent in a Ruby class, then call it with `.ask`.
+Start with an Agent: a Ruby class that gives a model instructions and operations
+it can call. This guide builds on the help center example in
+[Getting Started](getting_started.md), including its `HelpCenterLookupTool` and
+provider setup.
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
@@ -9,16 +12,20 @@ class CustomerSupportAgent < LittleGhost::Agent
   tools HelpCenterLookupTool
 end
 
-run = CustomerSupportAgent.ask("Where is my order?")
+run = CustomerSupportAgent.ask("What is the refund policy?")
 run.response
 ```
 
 From there, add only what the work needs. Give the agent a tool. Let it ask a specialist for help. Or coordinate several agents while the rest of your application keeps making the same call.
 
-## An Agent owns one model loop
+## An Agent carries a request through to an answer
 
 An **Agent** defines one model-driven behavior. It chooses the model, supplies the instructions and tools, and carries one request through to an answer.
 
+The model can answer immediately or ask to call a Tool. LittleGhost runs the
+Tool and sends its result back to the model, which can continue working. That
+back-and-forth is the **model loop**.
+
 The class holds the behavior you want to reuse. Each call brings its own input, history, context, settings, and attachments. Request data never needs to live on the class.
 
 ```text
@@ -60,71 +67,32 @@ inside the Tool using identity and account information from your application.
 [Tools](tools.md) follows that path from model input to application code,
 including run-scoped bindings, concurrency, retries, and sandbox delegation.
 
-## A Run owns one top-level execution
+## A Run records one request
 
 Every `.ask` or `.stream_ask` creates a **Run**. Think of it as the record of one trip through LittleGhost. It opens what the request needs, records how the work ended, and closes the resources it owns.
 
 ```ruby
-run = CustomerSupportAgent.ask("Where is order 481?")
+run = CustomerSupportAgent.ask("What is the refund policy?")
 
 run.completed? # => true
 run.response
-# One possible response: Order 481 is out for delivery.
-run.usage      # => normalized token usage
+# One possible response: Refunds are available within 30 days.
+run.usage      # Token counts reported by the model provider.
 run.result     # => the complete LittleGhost::RunResult
 ```
 
 The Agent defines reusable behavior; the Run records what happened this time.
 
-### Follow one request
-
-One Run owns the trip from request to result:
-
-```text
-Run
-├── Invocation: caller input, history, and application context
-├── RunContext: mutable working state for this execution
-└── Agent and Tools ──> RunResult
-```
-
-An **Invocation** is the request in LittleGhost's standard shape. Its `context`
-contains current request values supplied by your application. A Tool can read
-those values through `run.invocation.context` when it checks permission.
-
-A **Session** stores conversation state between Runs when persistence is
-configured. The **RunContext** carries mutable working state in `context.state`
-during one Run. LittleGhost loads saved Session state before adding the current
-Invocation context. Recheck saved values before using them for permission
-decisions.
-
-A Tool's **Binding** gives the Tool access to objects created for this run,
-including the Agent, Run, Workspace, and Sandbox. These objects are separate
-from arguments chosen by the model. [Tools](tools.md) explains the binding;
-[Workspaces and Sandboxes](sandboxing.md) explains delegated files and child
-processes.
-
-The final **RunResult** keeps the complete assembly result. Its `text` is the final text answer. Its `output` returns structured data when the Agent declared a result schema, and text otherwise. The top-level `Run#response` is always the caller-facing text.
-
-### See how a call ended
-
-Top-level calls normally return a Run, even when execution fails. The terminal event carries the same outcome when you stream:
+The final **RunResult**, available through `run.result`, holds the answer and
+details such as token usage. Its `output` returns text unless you configured
+the Agent to return checked data, such as a hash of named fields. See
+[Structured Results and Content](structured_outputs_and_content.md) for that
+alternative. Use `run.response` when you want the text answer.
 
-| What happened | Run outcome | Terminal event | What Ruby does |
-| --- | --- | --- | --- |
-| The assembly completed | `completed` | `:run_stop` | Returns the Run |
-| Model, provider, or assembly execution failed | `failed` | `:run_error` | Returns the Run; inspect `run.error` |
-| The deadline stopped work | `partial` | `:run_partial` | Returns the Run with any response produced so far |
-| Cancellation stopped work | `cancelled` | `:run_cancel` | Returns the Run without a response |
-| Tool input or a `ToolError` failed | The model may recover | No terminal event by itself | Gives a safe error result back to the model |
-| Input, configuration, or resources failed before a Run could start | No Run exists | None | Raises the exception |
-
-Unexpected Tool exception messages are hidden from the model. The original
-exception remains available to application callbacks and diagnostics.
-
-Failures while closing resources, delivering events, or reporting
-instrumentation sit outside the normal result path. They raise a Ruby exception
-because LittleGhost can no longer promise that it delivered a clean ending.
-[Running in Production](production.md) covers supervision and shutdown.
+When a Tool needs to know who is asking, pass information from your application
+with the request. [Tools](tools.md) explains how it reaches the Tool. When a
+conversation should continue across requests, a **Session** saves its history
+and working state; [Running in Production](production.md) covers that setup.
 
 ## An Assembly can look like one Agent
 
@@ -157,6 +125,10 @@ The coordination types differ mainly in who decides what happens next:
 
 A **subagent** is a specialist that a parent Agent can call for help. The parent model chooses when to delegate, reads the result, and then continues its own answer.
 
+The examples below omit the specialist Agent definitions. Each is an Agent
+class like `CustomerSupportAgent`, with instructions and tools suited to its
+task. [Compose Agents](assemblies.md) expands on these coordination patterns.
+
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
   model "openrouter:openai/gpt-5.6-luna"
@@ -166,15 +138,13 @@ end
 
 Use a subagent when delegation is part of one model's decision-making. Use a Workflow when application code must guarantee that a step happens.
 
-When an Agent also uses code mode, subagent controls stay in the Agent's
-conversation. Code-mode programs can compose ordinary Tools, while spawning,
-messaging, and checking on subagents remain decisions for the parent model.
-
 ### Workflows make Ruby the coordinator
 
 A **Workflow** coordinates work with ordinary Ruby. Its `perform` method can call an Agent or another Assembly, read a result, choose a branch, or run independent steps together.
 
-`invoke` prepares a lazy child call. Reading `.output` runs an intermediate child. Return the final `invoke` itself, without reading its output, so that answer can stream to the caller.
+`invoke` prepares a participant's call without running it yet. Read `.output`
+to run it and use its answer in Ruby. Return the final `invoke` call to use
+that participant's answer as the Workflow's result.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -192,6 +162,13 @@ class ResponseWorkflow < LittleGhost::Workflow
 end
 ```
 
+In this example, research finishes before the support Agent begins. `input.text`
+is the original question; the Workflow adds the research to it.
+
+You can also inspect an answer before choosing it as the final result, without
+running the participant again. [Compose Agents](assemblies.md) shows how, along
+with ways to display each participant's progress.
+
 Workflow children receive the caller's history and application context by default. Pass `history: []`, `context: {}`, or redacted values when a participant should receive less.
 
 ### Swarms let agents hand work to one another
@@ -216,7 +193,8 @@ Agent should use it as context rather than proof that an action is permitted.
 
 ### Graphs make routes visible
 
-A **Graph** connects named Assembly nodes with declared edges. Nodes can contain Agents, Workflows, Swarms, or other Graphs.
+A **Graph** lays out the steps and routes through a task. Each named **node**
+runs an Agent or another Assembly. An **edge** says which node can run next.
 
 ```ruby
 class SupportFlowGraph < LittleGhost::Graph
@@ -236,6 +214,10 @@ class SupportFlowGraph < LittleGhost::Graph
 end
 ```
 
+Here, `TriageAgent` is expected to answer `billing` for billing questions.
+That answer selects the conditional billing route. Otherwise, the unconditional
+general route is the fallback; it does not run alongside the billing route.
+
 Graph nodes receive the original task and results from the nodes immediately
 before them. They do not receive caller history or application context unless
 their declarations opt in. [Compose Agents](assemblies.md) explains parallel
@@ -256,6 +238,28 @@ run.result.trajectory.transitions
 This record shows which participants ran. [Compose Agents](assemblies.md)
 explains builders, detailed routing records, and live events from nested Agents.
 
+## Handle the outcome
+
+An Agent or coordinated Assembly normally returns a Run even when the work
+fails. Check its outcome before using the answer:
+
+| What happened | Run outcome | What to inspect |
+| --- | --- | --- |
+| Work completed | `completed` | `run.response` or `run.result` |
+| Model, provider, or assembly execution failed | `failed` | `run.error` |
+| The deadline stopped work | `partial` | Any response produced so far |
+| Cancellation stopped work | `cancelled` | No response is returned |
+
+A Tool error need not end the Run: LittleGhost can give the model a safe error
+result so it can try again. Unexpected exception messages stay in application
+diagnostics rather than going to the model.
+
+Some failures raise Ruby exceptions instead of returning a Run, including
+invalid setup before work starts and failures while closing resources or
+delivering events. [Running in Production](production.md) covers error handling
+and shutdown; [Run](rdoc-ref:LittleGhost::Run) lists the streaming events for
+each outcome.
+
 The pieces now fit together: Agents define behavior. Tools connect them to Ruby. Runs record one execution. Assemblies let the system grow without changing the caller.
 
 Continue with [Models and Providers](models_and_providers.md) to choose model

data/docs/guides/getting_started.md

@@ -17,7 +17,8 @@ $ export OPENROUTER_API_KEY="..."
 
 Use your application's secret manager outside a local shell, and never commit provider credentials.
 
-This guide uses OpenRouter to keep setup to one key. Prefer another hosted
+This guide uses OpenRouter, a service that sends requests to your chosen AI
+model. Set `OPENROUTER_API_KEY` to a key from your OpenRouter account. Prefer another hosted
 provider or a local model server? Start with [Provider Support](providers.md).
 
 ## See your first answer
@@ -41,10 +42,11 @@ else
 end
 ```
 
-Run the file and you have a working AI feature:
+`model` selects the service and model to call. `system_prompt` supplies the
+instructions the model follows on each request. Run the file with your bundle:
 
 ```sh
-$ ruby customer_support_agent.rb
+$ bundle exec ruby customer_support_agent.rb
 ```
 
 `CustomerSupportAgent.ask` creates a `LittleGhost::Run` for this request. When the work finishes, the Run holds the outcome and response.
@@ -55,7 +57,9 @@ The selected external provider may receive system instructions, caller input, co
 
 ## Connect the agent to your application
 
-The first agent can answer general questions. A **tool** gives it a focused operation backed by your Ruby code:
+The first agent can answer general questions. A **tool** gives it a focused
+operation backed by your Ruby code. Add this class after the `require` line,
+before `CustomerSupportAgent`:
 
 ```ruby
 class HelpCenterLookupTool < LittleGhost::Tool
@@ -80,7 +84,9 @@ class HelpCenterLookupTool < LittleGhost::Tool
 end
 ```
 
-Make the tool available to the agent and tell the model when to use it:
+`input_schema` describes the arguments the model may supply. Here, `topic` must
+be one of the help center's keys. Replace the Agent definition and the call at
+the end of the file with these:
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
@@ -106,84 +112,48 @@ LittleGhost checks the model's arguments before it calls
 `HelpCenterLookupTool#call`. The Tool's result then becomes context for the
 model.
 
-### Use application context for private data
-
-The schema checks shape, not permission. When a Tool reads private data or
-changes something, use identity and account information established by your
-application rather than asking the model to supply it.
-
-While an Agent is working, LittleGhost binds each Tool instance to the current
-Run. The Tool can read request values through its `run` accessor:
-
-```ruby
-class OrderStatusTool < LittleGhost::Tool
-  ORDER_STATUSES = {
-    ["user-7", "account-2", "481"] => "out for delivery"
-  }.freeze
-
-  description "Look up an order that belongs to the current customer."
-  input_schema(
-    type: "object",
-    properties: {order_number: {type: "string"}},
-    required: ["order_number"],
-    additionalProperties: false
-  )
-
-  def call(input)
-    lookup = [
-      run.invocation.actor_id,
-      run.invocation.context.fetch("account_id"),
-      input.fetch("order_number")
-    ]
-
-    ORDER_STATUSES.fetch(lookup) do
-      raise LittleGhost::ToolError, "Order not found"
-    end
-  end
-end
-
-class CustomerSupportAgent < LittleGhost::Agent
-  tools HelpCenterLookupTool, OrderStatusTool
-end
-
-run = CustomerSupportAgent.ask(
-  "Where is order 481?",
-  actor_id: "user-7",
-  context: {account_id: "account-2"}
-)
-```
-
-Here, `order_number` came from the model. The application supplied `actor_id`
-and `account_id` after authenticating the caller. LittleGhost places those
-request values on `run.invocation`; context keys become strings.
-
-> **Safety note:** Treat model-selected Tool arguments like any other external
-> input. Check permission using the current user and account before returning
-> private data or performing a write.
-
-That is enough to authorize the first Tool safely. [Core Concepts](core_concepts.md) names the request and working-state objects behind `run`, and [Running in Production](production.md) explains what changes when you add saved conversations.
+> **Safety note:** The schema checks arguments, not permission. This example
+> reads a public help center. Before a Tool returns private data or changes
+> anything, check permission using the user and account identified by your
+> application—not values supplied by the model. [Tools](tools.md) shows how to
+> pass that information to a Tool.
 
 ## Stream the same agent
 
-Use `.stream_ask` when a console, HTTP response, or user interface should receive progress as it happens:
+Use `.stream_ask` when a console, HTTP response, or user interface should receive
+the answer as it is written. Replace the `.ask` call with the following code.
+
+Each `:agent_stream` event contains the Agent's progress and a `source` that
+identifies which Agent produced it. The source check below selects the Agent
+you called directly: `/root` with no enclosing assembly steps. `:text_delta`
+contains the next piece of its answer.
 
 ```ruby
 stream = CustomerSupportAgent.stream_ask("Can I get a refund?")
 
 run = stream.each do |event|
   case event.type
-  when :text_delta
-    print event.data.fetch(:text)
+  when :agent_stream
+    source = event.data.fetch(:source)
+    next unless source.agent_path == "/root" && source.assembly_path.empty?
+
+    progress = event.data.fetch(:event)
+    print progress.data.fetch(:text) if progress.type == :text_delta
   when :run_error
     warn event.data.fetch(:message)
   end
 end
 
-puts "\n#{run.response}" if run.completed?
+run.response # The completed answer, separate from live progress.
 warn run.error.class.name if run.failed?
 ```
 
-The stream yields `LittleGhost::StreamEvent` values. Text, tool activity, usage, and completion all look the same across providers. When enumeration finishes, `.each` returns the same `LittleGhost::Run` that now holds the final outcome and response.
+When enumeration finishes, `.each` returns the Run with the final outcome and
+complete response. You can display progress and still read the finished answer.
+
+If you later add other Agents, their progress arrives in the same stream. Keep
+the source check when your audience should see only this Agent's text. See
+[Compose Agents](assemblies.md) to display several participants.
 
 ## Give the code a home
 
@@ -223,8 +193,8 @@ The source repository also contains a complete
 [single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
 and a
 [coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness)
-that demonstrates Agents, prompt views, Tools, a Graph, a Workspace, and a
-native Sandbox.
+that shows a larger application with several agents and tools for working
+with files.
 
 You now have the smallest useful LittleGhost application: one Agent, one Tool, and one familiar Ruby call.
 

data/docs/guides/integrations.md

@@ -27,10 +27,22 @@ events = LittleGhost::AGUI::Adapter.new.stream(
 events.each { |event| websocket.write(JSON.generate(event)) }
 ```
 
-The adapter translates the full Run, including model output, Tool activity,
-retries, subagent activity, and the final outcome. It does not keep state between
-calls. Your application owns the connection, backpressure, disconnect behavior,
-and any request state its callbacks need.
+The adapter translates Run lifecycle and final outcomes, plus selected Agent
+progress such as model output, Tool activity, and retries. By default, it selects
+only the root Agent: `agent_path == "/root"` with an empty `assembly_path`.
+Nested Agent progress is not forwarded. The adapter reads Agent progress from
+`:agent_stream` and reports aggregate usage separately.
+
+Pass `source_filter:` to `LittleGhost::AGUI::Adapter.new` to select other
+participants. This application-owned callable receives an `AgentStreamSource`
+and returns a truthy value only for sources the client may see. Match the
+enclosing assembly path as well as the Agent identity when selecting a nested
+participant. Computed assembly answers arrive in `RUN_FINISHED`'s result, not
+as synthetic text deltas.
+
+The adapter does not keep state between calls. Your application owns the
+connection, backpressure, disconnect behavior, and any request state its
+callbacks need.
 
 LittleGhost may emit event types beyond the core AG-UI set. Decide whether the
 client preserves or ignores types it does not recognize. See the [AG-UI event
@@ -38,8 +50,10 @@ documentation](https://docs.ag-ui.com/concepts/events) when implementing the
 client.
 
 > **Safety note:** A Run stream can include model output, Tool arguments and
-> results, errors, and participant activity. Check that the connected user may
-> see the complete Run, then filter fields before sending or storing events.
+> results, errors, and participant activity. Source selection controls which
+> Agent progress is forwarded; it does not redact that progress or filter the
+> final Run result. Check that the connected user may see those values, and
+> filter sensitive fields before sending or storing events.
 
 Calling `each` drives the source stream on the caller's fiber or thread. When a
 client disconnects, stop enumerating and decide whether the application should