little_ghost 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 450a61dddcb991278311cf48d3a86b65fa09930a939ad4cf877b226cf59be74b
-  data.tar.gz: ee6d950747b8b1ef19078c4e6c18252eb47cb8581def86efa266bf208703683c
+  metadata.gz: 9890ec252b435a45ce78f82a57b107fbfa7f1846f4cf580e0538ce3303c2d7c5
+  data.tar.gz: 47c8aa6beeaf56a8987088007fa67e56144394a3fff1dcdb8e357812725ab7e6
 SHA512:
-  metadata.gz: 0c726c4cae4d584facab0c7542f6f95b939ac6c8bac78ff3b5d525d5e47ce673280d773572243b61df14da8881b4105488beffa45b4659abffb40f11e71368ad
-  data.tar.gz: bc7d5f909e3d48382b889ad4d4cf8fadd2df7978b09069a20f7632da858f788d6210eb1a13921b232a1a5ebf8d25cebfa240e4c4090ef96d135df2d74f376e5a
+  metadata.gz: 92540329eaa105782f108dc52cf0e21351b7ae60c674d6b6d786a460b221e54f569ae7f3240bdb0d8a436ea6b0102ef1d14251fa543d2d9c7522aad6d9142f4a
+  data.tar.gz: 3dcb8b76e48448cbbd8088cfc0ee5ef0edcfcdb4b595c93ed741d60ee9f852a4ece504794119bdd874761ed1e40af97f7e05f6bb3f81884c9b8d4c4b0656a43a

data/README.md

@@ -6,7 +6,7 @@
 
 <hr>
 
-Bring agents and agentic workflows into an existing Ruby system, or use them as the core of a dedicated AI service. LittleGhost connects model providers, tools, streaming, sessions, delegation, deterministic workflows, and observability through Ruby APIs.
+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.
 
 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:
 
@@ -51,19 +51,33 @@ end
 
 ## How the pieces fit
 
+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:
+
 ```text
 provider connections + model selections ──> ModelResolver ──> provider
                                                │
 request ──> CustomerSupportAgent ──> HelpCenterLookupTool
                   │
                   └────────> ResearchAgent subagent
+```
+
+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:
+
+```text
+request ──> CustomerSupportAgent
 
 request ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent
+
+request ──> ProblemSolverSwarm ──> TriageAgent ──handoff──> BillingAgent
+
+request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseAgent
 ```
 
-Configuration owns shared services such as model resolution, sessions, lookup paths, workspaces, sandboxes, and instrumentation. Agent classes own behavior: their model selection, prompt, tools, limits, result schema, and delegation policy. Tools expose narrow application operations. A subagent lets the model delegate within configured limits; a workflow uses ordinary Ruby when the application must control ordering.
+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 a run lifecycle. The run checkpoints session state, closes its resources, aggregates usage, and emits framework events whether the entrypoint is an agent or a workflow.
+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
 
@@ -104,12 +118,12 @@ By default, LittleGhost maps `default` to GPT-5.6 Luna. It configures convention
 
 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.
 
-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/prompts`, `app/tools`, and `app/skills` are optional conventions. Every path can be configured, and agents, prompts, and tools may live wherever the application loads them.
+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`.
 
 ## Documentation
 
 - [Getting Started](docs/guides/getting_started.md) builds and streams the customer support example.
-- [Core Concepts](docs/guides/core_concepts.md) explains models, agents, tools, runs, delegation, workflows, and sessions.
+- [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.
 
 ## Contributing

data/docs/guides/core_concepts.md

@@ -1,6 +1,6 @@
 # Core Concepts
 
-LittleGhost gives Ruby software two ways to compose AI behavior. Agents can choose among validated tools and delegated specialists, while agentic workflows keep required ordering and branching under application control. The customer support example makes that boundary visible: ModelResolver chooses provider-backed models, CustomerSupportAgent owns behavior, HelpCenterLookupTool exposes a narrow help center lookup, ResearchAgent handles delegated investigation, and ResponseWorkflow imposes a deterministic sequence when the surrounding system requires one.
+Start with one agent. In LittleGhost, an **agent** is a reusable Ruby definition for one model loop: it selects a model, supplies instructions, exposes tools, and decides when the model has finished answering one request.
 
 ```text
 shared configuration
@@ -12,9 +12,31 @@ one request
     │   ├── HelpCenterLookupTool
     │   └── ResearchAgent subagent (model-directed)
     └── sessions, resources, usage, events, and terminal result
+```
+
+The sections below build outward from that unit. After the agent, the guide introduces its model, tools, and run lifecycle. It then names an **assembly**: anything a caller can invoke like one agent, including coordinated workflows, swarms, and graphs.
+
+## Agents declare one model-driven behavior
+
+An agent class keeps the behavior for one application role together:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  description "Answers customer support questions."
+  model :customer_support
+  system_prompt "Answer clearly. Check the help center before stating company guidance."
+  tools HelpCenterLookupTool
+end
+```
+
+The class-level DSL is inheritable. It can declare prompts, limits, callbacks, tool classes, structured results, context management, skills, and delegation. Capabilities remain inactive until their corresponding DSL is called.
+
+`CustomerSupportAgent.ask` creates a standalone entrypoint, consumes one `LittleGhost::Run`, and returns that run. `CustomerSupportAgent.stream_ask` creates the same entrypoint and yields events while it works. Create `CustomerSupportAgent.new(runtime:)` explicitly when several calls should reuse one runtime.
 
-one deterministic request
-└── Run ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent
+```ruby
+run = CustomerSupportAgent.ask("Can I get a refund?")
+run.response       # final text from the top-level execution
+run.result.output  # text, or a validated structured value when declared
 ```
 
 ## Models can be selected directly or by role
@@ -60,37 +82,26 @@ Dotted roles inherit from the nearest registered parent. `ResearchAgent` can req
 
 The provider performs model I/O. `LittleGhost::ModelResolver` resolves application intent into a `LittleGhost::Model`, which carries the provider, target, settings, details, and role for a run.
 
-## Agents declare behavior
-
-An agent class declares application behavior:
-
-```ruby
-class CustomerSupportAgent < LittleGhost::Agent
-  description "Answers customer support questions."
-  model "customer_support"
-  system_prompt "Answer clearly. Check the help center before stating company guidance."
-  tools HelpCenterLookupTool
-  subagent ResearchAgent, kind: "research"
-end
-```
+## Runs own top-level lifecycle
 
-The class-level DSL is inheritable. It can declare prompts, limits, callbacks, tool classes, structured results, context management, skills, and delegation. A capability mixin may be included in `LittleGhost::Agent`, but its behavior remains inactive until the corresponding DSL is called.
+A `LittleGhost::Run` owns one top-level execution. It opens the session, workspace, sandbox, agent entrypoint, and registered resources, then closes owned resources in reverse order. Later sections show how the same lifecycle can own a coordinated entrypoint.
 
-`CustomerSupportAgent.ask` creates a standalone entrypoint, builds and consumes a `LittleGhost::Run`, and returns that run. `CustomerSupportAgent.stream_ask` creates the same kind of entrypoint and yields the run's events. Create `CustomerSupportAgent.new(runtime:)` explicitly when several calls should reuse one runtime. Agents built by a runtime are instead scoped to their owning run and return a `LittleGhost::RunResult` from `#call`.
+The run is both executable and enumerable. `#call` consumes it; `#each` streams `LittleGhost::StreamEvent` objects. After termination, the run reports one outcome: completed, failed, partial at a deadline, or cancelled. It also exposes the final response, result, usage, and error.
 
-That distinction explains two useful return paths:
+Long-lived services can supervise a run without making their request thread own its execution:
 
 ```ruby
-run = CustomerSupportAgent.ask("Can I get a refund?")
-run.response       # final text from the top-level execution
-run.result.output  # text, or a validated structured value when declared
-```
-
-## Runs own top-level lifecycle
+execution = CustomerSupportAgent.new.start_execution(
+  message: "Investigate transfer 481"
+) do |event|
+  event_buffer << event
+end
 
-A `LittleGhost::Run` owns one top-level agent or workflow execution. It opens the session, workspace, sandbox, entrypoint, and registered resources, then closes owned resources in reverse order.
+execution.interrupt_response(message: "Include the latest ledger entry")
+run = execution.wait(deadline: Time.now + 30)
+```
 
-The run is both executable and enumerable. `#call` consumes it; `#each` streams `LittleGhost::StreamEvent` objects. After termination, the run reports one outcome: completed, failed, partial at a deadline, or cancelled. It also exposes the final response, result, usage, and error.
+`LittleGhost::Execution` owns the worker, preserves request-scoped execution state, and coordinates cancellation, interruptions, waiting, and bounded shutdown. The underlying run still owns agent resources and its terminal outcome. Event consumers run on the worker thread. Applications should keep them thread-safe and avoid blocking indefinitely.
 
 An `Invocation` is the request envelope. It normalizes the current message and history, generates missing identifiers, and retains application-specific fields with indifferent string and symbol keys. Caller identity remains explicit. If session persistence needs tenant isolation, derive its actor from trusted authentication state; never trust a model-supplied or unverified request field.
 
@@ -116,8 +127,31 @@ end
 
 LittleGhost validates the model's input before invoking `#call`. Hashes and arrays returned by a tool are JSON-encoded; other values become text. Expected application failures can raise `LittleGhost::ToolError`; unexpected exception messages are sanitized before they reach model context.
 
+A tool can return a `LittleGhost::Tool::ExecutionResult` with `companion_content` when the next model request also needs text, images, or documents. LittleGhost keeps the ordinary tool result intact, then appends each tool's companion blocks as a transient user message in tool-call order. Session persistence omits those transient messages. Tool-use, tool-result, and reasoning blocks are rejected as companion content.
+
 Validation is not authorization. A tool that reads customer records, writes files, executes processes, or calls a network service must enforce the application's trust rules itself. The built-in unrestricted sandbox executes with the Ruby process's permissions and is not a security boundary. Configure an isolated sandbox before exposing filesystem or shell tools to untrusted work.
 
+## Assemblies let coordination look like one agent
+
+An **assembly** is any LittleGhost entrypoint that a caller can use like one agent. `CustomerSupportAgent` is therefore the smallest assembly: it contains one agent and one model loop.
+
+When a feature needs several agents, three coordination classes preserve that same caller interface:
+
+- A `Workflow` uses Ruby code to enforce ordering, branching, and parallel work.
+- A `Swarm` lets configured agents choose direct handoffs to one another.
+- A `Graph` follows named nodes and application-declared edges.
+
+```ruby
+CustomerSupportAgent.ask("Can I get a refund?")
+ResponseWorkflow.ask("Can I get a refund?")
+ProblemSolverSwarm.ask("Can I get a refund?")
+SupportFlowGraph.ask("Can I get a refund?")
+```
+
+Each call returns a top-level `LittleGhost::Run`, and each `stream_ask` yields the same event vocabulary. The caller chooses an entrypoint without needing to branch on its internal coordination style. Instances also share `call`, `stream`, `start_execution`, interruption, and `as_tool` behavior.
+
+Keep agent definitions in `app/agents`. Put workflow, swarm, and graph definitions in `app/assemblies`, with class names ending in `Workflow`, `Swarm`, or `Graph`. The next sections explain when each form earns its name.
+
 ## Subagents are model-directed delegation
 
 Declaring `ResearchAgent` as a subagent gives `CustomerSupportAgent` a configured set of tools for spawning, messaging, interrupting, waiting for, and listing research work:
@@ -162,23 +196,115 @@ class ResponseWorkflow < LittleGhost::Workflow
 end
 ```
 
-`#invoke` builds a lazy agent invocation. Calling `#output` consumes an intermediate invocation; `#perform` must return its final invocation unconsumed so LittleGhost can stream that agent to the original caller. Input, history, state, settings, cancellation, deadline, template values, and trace parentage flow through the workflow, while intermediate usage is added to the terminal result.
+`#invoke` builds a lazy Assembly invocation, so a workflow step may be an agent, workflow, swarm, or graph. Calling `#output` consumes an intermediate invocation; `#perform` must return its final invocation unconsumed so LittleGhost can stream it to the original caller. Input, history, state, settings, cancellation, deadline, template values, and trace parentage flow through the workflow, while intermediate usage is added to the terminal result.
+
+Unlike Graph nodes and Swarm members, each Workflow invocation receives the full caller history and application context by default. Isolated copies prevent one child from mutating a sibling's context; they do not prevent disclosure. Pass `history: []`, `context: {}`, or explicitly redacted values to `invoke` when participants use different providers or privileges.
+
+Independent invocations can run concurrently while ordinary Ruby still controls composition:
+
+```ruby
+research, verification = parallel(
+  invoke(ResearchGraph, as: :research),
+  invoke(VerificationWorkflow, as: :verification),
+  max_concurrency: 2
+)
+```
+
+Results preserve declaration order. Each branch receives isolated application context and cooperative cancellation. `timeout:`, `retries:`, `retry_on:`, and `retry_delay:` apply to `invoke`; retries require explicit exception classes because rerunning an Assembly may repeat tool side effects.
+
+Cancellation, deadlines, and step timeouts are cooperative. They do not forcibly stop provider or tool code, and they do not roll back external side effects. A participant must honor its cancellation token or deadline, and applications must decide whether an operation is safe to retry.
 
-A workflow is an explicit entrypoint on a run:
+A workflow has the same entrypoint API as an agent:
 
 ```ruby
-runtime = LittleGhost::Runtime.new(configuration: LittleGhost.configuration)
-run = runtime.build_run(
-  {message: "Review this unusual refund request"},
-  agent_class: CustomerSupportAgent,
-  entrypoint_class: ResponseWorkflow
-).call
+run = ResponseWorkflow.ask("Review this unusual refund request")
 
 puts run.response
 ```
 
 Choose a subagent when delegation is part of the model's judgment. Choose a workflow when ordering and branching are application invariants. They can coexist: `ResponseWorkflow` can always collect baseline research, while `CustomerSupportAgent` can still delegate a new question that arises while drafting the response.
 
+## Swarms use direct agent handoffs
+
+A swarm keeps one member active at a time and injects one reserved `handoff_to_agent` tool. A member either answers the caller or hands the request directly to another configured member:
+
+```ruby
+class ProblemSolverSwarm < LittleGhost::Swarm
+  member TriageAgent
+  member BillingAgent
+  member AccountAgent
+  start TriageAgent
+  handoff TriageAgent, to: [BillingAgent, AccountAgent]
+  max_steps 12
+  max_handoff_repeats 3
+end
+```
+
+Members are fresh Agent instances; unlike Workflow invocations and Graph nodes, Swarm members intentionally remain Agent-only so handoffs stay direct and local. A complete Swarm can still be used as a Workflow step, Graph node, or tool. A handoff names the next member and supplies a message plus optional JSON-like context. That context remains untrusted model-authored prompt content; it does not become trusted application state. A member cannot hand off to itself, hand off outside the allowed topology, or combine a handoff with another tool call. Without `handoff` declarations, routing remains all-to-all except self-handoffs. A member with no declared outgoing target receives no handoff tool. Invalid calls return an ordinary tool error so the model can recover. If no handoff occurs, the current member's response is final. Members receive only the current request or explicit handoff envelope by default; opt into original caller data with `history: true` or `context: true` on that member.
+
+Potentially intermediate model text is omitted from the caller's ordinary response stream. Streams expose Assembly lifecycle events, then the final member's ordinary response events. `max_steps` bounds total work and `max_handoff_repeats` detects repeated directed transitions; either limit raises `AssemblyLimitError` when exhausted. Members also accept the shared cooperative retry and timeout options described for workflows.
+
+## Graphs guide serial and parallel paths
+
+A graph names Assembly nodes and directed edges. Ordinary edges select exactly one next node, while explicit forks and joins add bounded parallel work without shared mutable reducers:
+
+```ruby
+class SupportFlowGraph < LittleGhost::Graph
+  node :triage, TriageAgent
+  node :research, ResearchAgent
+  node :verify, VerificationWorkflow
+  node :respond, CustomerSupportAgent
+
+  start :triage
+  fork :triage, to: [:research, :verify], max_concurrency: 2
+  join [:research, :verify], to: :respond
+  finish :respond
+  max_steps 12
+end
+```
+
+An edge condition receives immutable `Graph::State`, including the original input, history, context, step, current and previous node names, predecessors, branch results, completed results, and a routed error when present. Exactly one matching conditional edge wins; otherwise one unconditional fallback is used. An `error_edge` can route selected application errors after retries are exhausted. Cancellation, parent deadlines, and cleanup failures always remain control flow.
+
+By default, a downstream node receives the original multimodal input plus labeled predecessor output. A join receives every branch output in declaration order. Pass `input: ->(state) { ... }` on an edge, error edge, or join to replace that mapping. Nodes receive no caller history or application context unless their declaration opts in with `history: true` or `context: true`. The original request and routed outputs still cross node and provider boundaries by default, and routing callbacks can inspect the original context through `Graph::State`; map or redact inputs explicitly when participants have different privileges. Nodes may name any Assembly type, class, builder, or immutable definition. Fork branches may follow ordinary edges before reaching their distinct declared join sources.
+
+`validate!` catches invalid topology before model work begins, and `to_mermaid` renders a deterministic diagram. A graph suppresses intermediate ordinary model stream events, publishes lifecycle, transition, fork, join, retry, and error events, aggregates usage, and forwards only the finish node's ordinary response stream. Downstream nodes still receive routed outputs, and terminal step records retain bounded semantic outputs for callers to inspect.
+
+Composite `RunResult` objects expose immutable `steps` and a `trajectory`. Step records include participants, attempts, timing, usage, relationships, and bounded semantic outputs without retaining transcripts or tool payloads. Swarm handoffs retain only their explicit handoff envelope. These records support assertions such as `result.trajectory.concurrent?(first_id, second_id)` without coupling tests to a tracing backend.
+
+## Builders unlock definitions discovered at runtime
+
+Class definitions are the default because they keep behavior, names, and topology close together. Each agent or assembly class can produce an immutable `.definition` snapshot or an independent mutable `.to_builder` variant.
+
+Use a builder when application code discovers participants or routes at runtime. The builder records the same declaration that the class DSL would organize:
+
+```ruby
+graph = LittleGhost::GraphBuilder.new(id: "support_flow")
+graph.node :triage, TriageAgent
+graph.node :respond, CustomerSupportAgent
+graph.start :triage
+graph.edge :triage, :respond
+graph.finish :respond
+graph.validate!
+
+run = graph.ask("Can I get a refund?")
+```
+
+`AgentBuilder`, `WorkflowBuilder`, `SwarmBuilder`, and `GraphBuilder` share the Assembly execution API. Builders remain mutable; each build or invocation recursively snapshots declaration containers and referenced Assembly definitions, so later builder declarations affect only future executions. Definitions are Ruby objects rather than portable JSON because conditions, callbacks, workflow bodies, factories, and resolvers may contain executable Ruby. Those closures and their external dependencies remain live trusted application code; the snapshot does not freeze state they capture.
+
+## Assemblies can be tools
+
+Any assembly instance supports `as_tool`. Agent classes can also declare another assembly as a tool:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  assembly_as_tool SupportFlowGraph, name: "investigate_support_case"
+end
+```
+
+`assemblies_as_tools` declares several with shared options. Existing `agent_as_tool` and `agents_as_tools` remain agent-specific aliases. Composite assemblies do not accept agent-only model or tool overrides.
+
+An assembly tool receives the invoking tool context's application state on every call. `preserve_context: false` prevents conversational history from carrying between calls; it does not suppress that application state. Nested tools must continue to authorize privileged work from trusted context rather than from model-authored input.
+
 ## Structured results separate data from prose
 
 An agent that feeds application code can declare a strict JSON object schema:
@@ -209,15 +335,18 @@ Use structured results when code consumes fields. Keep ordinary text when a huma
 
 The default session store is in-memory. A configured `SessionStore` can load history and state before an agent runs and checkpoint coherent turns as work progresses. The application must supply stable session and actor identifiers when it wants continuity and isolation.
 
+Applications that need to reconcile persisted messages with invocation history can register a `LittleGhost::Runtime::Hook` and implement `session_history`. The hook receives the run plus `stored:` and `fallback:` message collections. Return the history to use, or `nil` to defer to the next hook and ultimately the session default. This keeps application-specific reconciliation policy outside the framework session type.
+
 Streams expose generic framework events rather than provider wire formats. Consumers can render text deltas, observe tool or subagent activity, collect usage, and react to terminal outcomes without coupling to OpenAI, OpenRouter, or Bedrock. The optional AG-UI adapter translates the same events at an interface boundary.
 
 ## Keep the boundary visible
 
-The core design can be summarized as four choices:
+The core design can be summarized as five choices:
 
 - Put shared construction and provider policy in configuration; use inline declarations or independent YAML files according to the application's needs.
 - Put model behavior and available capabilities on agent classes.
 - Put privileged application operations behind narrow, authorized tools.
-- Put mandatory ordering in workflows; leave optional delegation to subagents.
+- Put imperative ordering in workflows, dynamic peer routing in swarms, and guided routing in graphs.
+- Leave addressable background delegation to subagents.
 
-Return to [Getting Started](getting_started.md) for the complete first-run setup. The API reference covers exact signatures and lifecycle details for `LittleGhost::Runtime`, `LittleGhost::Run`, `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Workflow`, and `LittleGhost::ModelResolver`.
+Return to [Getting Started](getting_started.md) for the complete first-run setup. The API reference covers exact signatures and lifecycle details for `LittleGhost::Runtime`, `LittleGhost::Run`, `LittleGhost::Execution`, `LittleGhost::Assembly`, `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Workflow`, `LittleGhost::Swarm`, `LittleGhost::Graph`, and `LittleGhost::ModelResolver`.

data/docs/guides/getting_started.md

@@ -120,7 +120,7 @@ Both calls use the same agent definition and active LittleGhost configuration. C
 
 ## Add a model role when the application grows
 
-Direct targets keep a small application easy to read. A larger application can give the same selection a stable role, then change the underlying provider, model, and defaults without editing each agent class:
+Direct targets keep a small application's model choice beside its behavior. A larger application can give the same selection a stable role, then change the underlying provider, model, and defaults without editing each agent class:
 
 ```ruby
 LittleGhost.configure do |config|
@@ -155,10 +155,14 @@ end
 
 Here, `provider` names a configured connection and every other key after `model` is a trusted model setting. Provider connections and model profiles may instead come from independent YAML files under `config/little_ghost`, or from paths selected in `LittleGhost.configure`. Inline declarations take precedence over explicit paths, which take precedence over conventional files; environment-based selection and the built-in default are the final fallback. `LittleGhost::Agent` and `LittleGhost::Configuration` document the complete shapes and precedence.
 
-## Fit LittleGhost into your application
+## Fit the agent into your application
 
-LittleGhost does not require an application layout. Keep agents and tools beside related application code when your framework or loader already has a home for them. If you want LittleGhost to eager-load these definitions, `app/agents` and `app/tools` are available conventions, and every lookup path is configurable.
+LittleGhost does not require an application layout. Keep agents and tools beside related application code when your framework or loader already has a home for them. If you want LittleGhost to eager-load definitions, use `app/agents` for agents and `app/tools` for tools.
+
+The agent in this guide owns one model loop. A larger feature may coordinate several participants while preserving the same `ask` and `stream_ask` entrypoints. LittleGhost calls any such callable unit an **assembly**. Workflows, swarms, and graphs are three kinds of coordinated assembly, and they conventionally live in `app/assemblies`. Their class names should state the coordination style, such as `DevelopmentWorkflow`, `ProblemSolverSwarm`, or `SupportFlowGraph`.
+
+Classes are the default way to organize reusable definitions. Core Concepts first explains when to choose each assembly type, then introduces builders for definitions discovered at runtime.
 
 Hosting remains the surrounding application's responsibility. A Rails controller, Rack endpoint, background job, CLI, or another Ruby entrypoint can call the same agent APIs shown above.
 
-Read [Core Concepts](core_concepts.md) next for model selection, reusable runtimes, subagents, workflows, sessions, and the boundaries between them. The API reference covers exact signatures for `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Configuration`, and `LittleGhost::Run`.
+Read [Core Concepts](core_concepts.md) next. It begins with the agent you built here, then adds model selection, runs, assemblies, subagents, workflows, swarms, graphs, builders, sessions, and the boundaries between them. The API reference covers exact signatures for `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Run`, and the coordination classes.

data/lib/little_ghost/agent/delegation.rb

@@ -30,7 +30,7 @@ module LittleGhost
           default: Subagents::Manager::DEFAULT_WAIT_TIMEOUT
         base.class_attribute :subagent_declarations_value, default: []
         base.class_attribute :subagent_resolvers_value, default: []
-        base.class_attribute :agent_tool_declarations_value, default: []
+        base.class_attribute :assembly_tool_declarations_value, default: []
       end
 
       # Exposes delegation declarations on agent classes.
@@ -95,25 +95,52 @@ module LittleGhost
         # conversational history between calls to that tool instance.
         def agent_as_tool(agent_class, name: nil, description: nil, model: nil, tools: nil,
           preserve_context: false)
+          assembly_as_tool(
+            agent_class,
+            name:,
+            description:,
+            model:,
+            tools:,
+            preserve_context:
+          )
+        end
+
+        # Exposes an Agent, Workflow, Swarm, or Graph as one ordinary tool.
+        # Agent-only +model+ and +tools+ overrides are rejected for composites.
+        def assembly_as_tool(assembly_class, name: nil, description: nil, model: nil, tools: nil,
+          preserve_context: false)
+          unless assembly_class.is_a?(Class) && assembly_class <= Assembly
+            raise ConfigurationError, "Delegated assemblies must inherit from LittleGhost::Assembly"
+          end
           validate_delegated_tools!(tools)
+          if !(assembly_class <= Agent) && (model || tools)
+            raise ConfigurationError, "Composite assemblies do not accept delegated model or tool overrides"
+          end
           declaration = {
-            agent: agent_class,
-            name: (name || agent_class.agent_id).to_s,
-            description: description || agent_class.description,
+            assembly: assembly_class,
+            name: (name || assembly_class.assembly_id).to_s,
+            description: description || assembly_class.description,
             model:,
             tools:,
             preserve_context:
           }
-          self.agent_tool_declarations_value = [*agent_tool_declarations, declaration]
+          self.assembly_tool_declarations_value = [*assembly_tool_declarations, declaration]
         end
 
         # Exposes several agent classes as ordinary tools with shared options.
         def agents_as_tools(*agent_classes, **options)
           agent_classes.each { |agent_class| agent_as_tool(agent_class, **options) }
-          agent_tool_declarations
+          assembly_tool_declarations
+        end
+
+        # Exposes several assembly classes as ordinary tools with shared options.
+        def assemblies_as_tools(*assembly_classes, **options)
+          assembly_classes.each { |assembly_class| assembly_as_tool(assembly_class, **options) }
+          assembly_tool_declarations
         end
 
-        def agent_tool_declarations = agent_tool_declarations_value # :nodoc:
+        def assembly_tool_declarations = assembly_tool_declarations_value # :nodoc:
+        def agent_tool_declarations = assembly_tool_declarations # :nodoc:
 
         private
 

data/lib/little_ghost/agent/tool_loop.rb

@@ -176,7 +176,8 @@ module LittleGhost
         replacement = Tool::ExecutionResult.new(
           content: "#{warning}\n\n#{result.content}",
           status: result.status,
-          error: result.error
+          error: result.error,
+          companion_content: result.companion_content
         )
         Support::Callbacks.replace(payload.merge(result: replacement))
       end