little_ghost 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2136594414b7f1c810eba51718916646506a4816ced53cf088034e091a0af5c
-  data.tar.gz: a7a2a279680b64f936096f70772374b3dcfc1ba21dfb2e428da91be22d385af4
+  metadata.gz: c6ec454a6085af7b0e2519eb0137e2f70115f0c00197d9f1914ac336c9fe4810
+  data.tar.gz: bde8feed25fc76a6e0290ec8462b12eb5b2df90c368214850caaa705a3da75d2
 SHA512:
-  metadata.gz: 3c78c760b8b9be5bb9aa3394fffdcc0735173366826b263534421c9755f0b0f458b4d14f75c65bee76bb8da839beb67917e6ce222d438073bef95f9258c23ec0
-  data.tar.gz: 6effec94de30f7b4e1ed5fcad776cd9579da8645a95ca510ebe5ee5a26921ded2c34eae8f50b70295e326c6874135cd7293de202874980da957ca73558852fe9
+  metadata.gz: 0c7081dc35068d5e3e3e0d917e4f024657cbecc117a0952b4ccfa329a9a4be2de77a96c87d9d7cf1eb3f9092219ed108d07422fa501e427542fdfb400aaf3e4a
+  data.tar.gz: 939d5fac29d8a1607225185f09784e2fe014d7ef20c20ba856ebda0b30c8e6634a79a9ff94725287f924576caecb2080204dec5fa7b36af3b801d02c3d9de93c

data/README.md

@@ -1,5 +1,10 @@
 # Build AI features that feel at home in Ruby
 
+> **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.
+
 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:
 
 ```ruby
@@ -17,7 +22,10 @@ run.response
 
 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 external provider. Model wording can vary between runs. Choose providers and the data you send them with the same care as any other external service.
+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.
 
 ## Install the gem
 
@@ -63,7 +71,13 @@ class CustomerSupportAgent < LittleGhost::Agent
 end
 ```
 
-The schema checks the shape of the input. Your Ruby code still decides whether the operation is allowed and safe. The result goes back to the model as context.
+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.
 
 ## Grow without changing the caller
 
@@ -99,16 +113,24 @@ 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.
 
-**Growing in public.** LittleGhost is under active development, and interfaces may evolve between releases. Pin the gem version and review release notes when upgrading.
+LittleGhost is pre-1.0. Pin the gem version and review release notes before
+upgrading, because interfaces may change between releases.
 
 ## Keep going
 
 - [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.
-- [Compose Agents](docs/guides/assemblies.md) walks through workflows, swarms, graphs, nesting, and builders.
+- [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.
-- [Running in Production](docs/guides/production.md) covers configuration, sessions, execution, observability, and trust boundaries.
-- [API reference](rdoc-ref:LittleGhost) provides exact signatures and lifecycle contracts.
+- [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.
 
 ### For contributors
 

data/docs/guides/assemblies.md

@@ -2,7 +2,7 @@
 
 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.
 
-## Start with the shared contract
+## Call every assembly the same way
 
 Callers do not need a branch for each implementation:
 
@@ -136,7 +136,9 @@ Opt in only for a member that needs the data:
 member AccountAgent, history: true, context: true
 ```
 
-Intermediate model text stays out of the caller-facing stream, leaving one coherent public answer. This is not a privacy boundary. The next member receives the handoff, and the result keeps a bounded summary of the journey.
+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
 
@@ -163,19 +165,19 @@ end
 SupportFlowGraph.validate!
 ```
 
-Conditions and input mappers read an immutable `Graph::State`. At most one conditional edge may match. If several match, LittleGhost raises `AssemblyRoutingError` instead of guessing which one wins. One unconditional edge can catch the request when none match.
+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. They still receive the original input or the output routed from an earlier node. Map or redact that data before it moves to a provider or participant that should see less.
+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 for a trusted node when it needs caller context:
+Opt in when a node needs caller context:
 
 ```ruby
 node :account_lookup, AccountLookupAgent, context: true
 ```
 
-### Fork and join bounded parallel paths
+### Run bounded parallel paths
 
-Use a fork when one result should start several independent branches. A join brings their answers back together:
+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
@@ -185,16 +187,88 @@ class InvestigationGraph < LittleGhost::Graph
   node :respond, CustomerSupportAgent
 
   start :triage
-  fork :triage, to: [:ledger, :policy], max_concurrency: 2
-  join(
-    [:ledger, :policy],
-    to: :respond,
-    input: ->(state) { state.branch_results.transform_values(&:output) }
-  )
+  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.
@@ -217,6 +291,50 @@ A timeout asks the running code to stop; it cannot forcibly end arbitrary Ruby o
 
 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:
@@ -232,7 +350,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 instrumentation when trusted operators need deeper diagnostics.
+Step outputs and buffered events have size limits. Use your application's
+instrumentation when you need deeper diagnostics.
 
 ## Compose assemblies inside assemblies
 
@@ -259,11 +378,17 @@ class SupportCoordinatorAgent < LittleGhost::Agent
 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. Any nested Tool doing privileged work must authorize with values the application established for the current request or checked again after loading.
+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 trusted application configuration decides the nodes or routes:
+Classes are the preferred form in application code. Use a builder when runtime
+configuration decides the nodes or routes:
 
 ```ruby
 graph = LittleGhost::GraphBuilder.new(
@@ -283,4 +408,5 @@ 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 [Prompts as Views](prompt_views.md) to give each Agent's growing instructions and shared prompt pieces a natural home.
+Continue with [Skills](skills.md) when an Agent should discover focused
+instructions and supporting resources only when a task needs them.

data/docs/guides/code_mode.md

@@ -0,0 +1,275 @@
+# Code Mode
+
+Code mode lets an Agent solve a multi-step Tool task in one small program. The
+model can gather independent results, filter them, and combine them before it
+returns to the conversation. Your Ruby Tools keep their usual permission
+checks.
+
+Start by adding code mode to an Agent that already has a Tool:
+
+```ruby
+class HelpCenterLookupTool < LittleGhost::Tool
+  tool_name "help_center_lookup"
+  description "Find a support answer by topic."
+  input_schema(
+    type: "object",
+    properties: {query: {type: "string"}},
+    required: ["query"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    entries = {
+      "refund policy" => "Refunds are available within 30 days.",
+      "shipping policy" => "Standard shipping takes three to five days."
+    }
+    entries.fetch(input.fetch("query"), "No matching entry.")
+  end
+end
+
+class ResearchAgent < LittleGhost::Agent
+  tools HelpCenterLookupTool
+  code_mode
+end
+```
+
+The language adapter that runs the program is called an engine. By default,
+LittleGhost uses its Ruby engine and the native Sandbox for the host operating
+system. It fails closed when that Sandbox is unavailable.
+
+Code mode adds three control Tools to the conversation. `exec` starts a
+program, `wait` checks on a program that is still working, and `stop` ends work
+that is no longer needed. The model can now send Ruby like this to `exec`:
+
+```ruby
+results = tools.parallel(
+  -> { tools.help_center_lookup(query: "refund policy") },
+  -> { tools.help_center_lookup(query: "shipping policy") }
+)
+
+text(results.join("\n"))
+```
+
+LittleGhost turns the Agent's Tool schemas into Ruby method signatures. The
+model sees those signatures and the available Tool names in its instructions.
+Those names, descriptions, and signatures form the code-mode Tool catalog. The
+model can compose the results with ordinary Ruby values instead of guessing
+how to call each Tool.
+
+## See what runs where
+
+The program runs in a child interpreter. The Tools do not.
+
+```text
+model
+  │ writes a program
+  ▼
+exec ──> sandboxed Ruby process
+             │ tools.help_center_lookup(...)
+             ▼
+          Tool broker in the parent Ruby process
+             │ normal Tool execution
+             ▼
+          HelpCenterLookupTool#call
+```
+
+The Tool broker receives interpreter calls in the parent Ruby process. It
+accepts only Tools registered on the Agent, then sends each call through the
+same validation, permission checks, limits, callbacks, events, and tracing used by
+a direct Tool call.
+
+Public streams show the brokered Tools by name. They omit the `exec`, `wait`,
+and `stop` bookkeeping. Traces still record the control operation around its
+nested Tool calls, so you can follow the complete execution.
+
+Code mode does not change what a Tool can do. A Tool still runs as application
+code, while the generated program runs in the configured Sandbox. Read
+[Tools](tools.md) for Tool permission checks and [Workspaces and
+Sandboxes](sandboxing.md) before giving generated programs file or process
+access.
+
+## Compose Tool calls with Ruby
+
+Each `exec` starts a fresh Ruby process. Local variables, constants, and globals
+do not carry into a later `exec`. Within one program, the model can use:
+
+- Named methods such as `tools.help_center_lookup(query: "refund policy")`.
+- `tools.call(name, arguments)` when the Tool name is dynamic.
+- `tools.parallel` for independent calls whose results should preserve input
+  order.
+- `ALL_TOOLS` to inspect the complete runtime catalog.
+- `text(value)` to add user-visible output.
+- The program's final expression as the completed value returned by `exec` or
+  a later `wait`.
+- `finish(value)` to complete early.
+
+The dynamic form accepts either the catalog name (`"help_center_lookup"`) or
+the matching method name (`"tools.help_center_lookup"`).
+
+JSON Tool results arrive as ordinary Ruby hashes, arrays, strings, numbers,
+booleans, or `nil`. When a Tool returns `Tool::Result`, code mode uses its
+Ruby `value`. Artifact bytes are not copied into program variables; the
+artifacts return to the model once with the surrounding `exec` or `wait`
+result. Stored references appear only when native media delivery exceeds its
+limit. A Tool failure raises inside the program so its Ruby code can handle the
+failure or return an error.
+
+Fresh processes keep interpreter state from leaking across programs. Each Ruby
+program also gets a temporary Workspace. LittleGhost removes it when the
+program ends, so files created directly by the interpreter do not carry into a
+later `exec`.
+
+A brokered filesystem Tool uses the Agent Run's separate Workspace. Files
+written through that Tool follow the Run Workspace's cleanup rules and may
+persist.
+
+## Check on work that takes longer
+
+Most programs finish while `exec` is watching them, so their result is ready in
+the same Tool call. If a program is still active after one minute, `exec`
+returns `still_working`. The program keeps running. The model can call `wait`
+to watch for up to another minute or `stop` when it no longer needs the result.
+
+Both `exec` and `wait` return as soon as the program finishes. The one-minute
+window is a maximum observation time, not a delay added to every call.
+
+`wait` does not resume, restart, or extend the program. It returns only output
+produced since the previous `exec` or `wait`. The returned status tells the
+model what to do next:
+
+- `still_working` means the program is active. Call `wait` again when its result
+  is still needed, or call `stop` to end it.
+- `completed`, `error`, and `terminated` are final. There is no program to wait
+  for after one of these statuses.
+
+The built-in engines give each program a total lifetime of one hour by default.
+That deadline begins at `exec` and does not reset when the model calls `wait`.
+The engine ends and cleans up an expired program even if the model never checks
+on it again. Applications can configure a shorter total lifetime with
+`wall_seconds`; the one-minute observation window remains fixed.
+
+A code-mode session owns the engine's active child process and related
+resources. It accepts only one `exec`, `wait`, or `stop` operation at a time.
+The Agent closes the session when its current call ends, including after a
+failure or cancellation. Cleanup failures raise because LittleGhost cannot
+claim that the child process and its resources ended cleanly.
+
+## Keep a Tool in the conversation
+
+With code mode enabled, ordinary Agent Tools move into the program catalog. The
+model-facing controls become `exec`, `wait`, and `stop`. Use `except` when an
+application Tool should remain available to the conversational model instead
+of moving into the program:
+
+```ruby
+class ResearchAgent < LittleGhost::Agent
+  tools HelpCenterLookupTool, ConfirmTool
+  code_mode except: ["confirm_tool"]
+end
+```
+
+Exclude a Tool when the conversational model should call it as a distinct
+decision—for example, a final confirmation that must remain visible as its own
+step. `except` uses each Tool's model-visible name; `ConfirmTool` defaults to
+`confirm_tool`. Calls made inside and outside code mode share the Agent's
+Tool-call limit. The `exec`, `wait`, and `stop` controls manage execution. They
+do not count toward that application Tool limit themselves.
+
+Subagent controls also stay in the conversation. They are orchestration choices
+for the parent model, not functions available inside a code-mode program.
+Code-mode `wait` watches an interpreter program; `wait_for_subagents` checks on
+delegated Agents. [Core Concepts](core_concepts.md#subagents-bring-in-a-specialist)
+explains model-directed delegation.
+
+## Set limits for the work you expect
+
+The Ruby engine sets limits for source and output size, memory, total and CPU
+time, file size, the number of programs, Tool calls, concurrency, and cleanup.
+Override only the limits your workload needs to change:
+
+```ruby
+LittleGhost.configure do |config|
+  config.code_mode = {
+    engine: :ruby,
+    sandbox: :native,
+    limits: {
+      programs: 16,
+      wall_seconds: 900,
+      cleanup_seconds: 5
+    }
+  }
+end
+```
+
+Bubblewrap owns the program's process tree but does not cap its process or thread
+count. Use an outer cgroup or container supervisor when generated code needs a
+hard task-count limit.
+
+Application defaults apply to every Agent that declares `code_mode`. An Agent
+can override the engine, Sandbox, limits, or excluded Tools in its own
+declaration.
+
+The operating-system Sandbox contains the interpreter. The parent Ruby process
+starts it, brokers Tool calls, and cleans it up. Language restrictions alone
+cannot contain native extensions, interpreter bugs, files, subprocesses, or
+sockets.
+
+Use an enforcing Sandbox backend for model-written code. Before production,
+test the deployed backend against the files, child processes, networking, and
+resource pressure your application expects. Also test cancellation and cleanup
+on the deployed host.
+
+## Opt into JavaScript when it fits
+
+The JavaScript engine is optional. It uses MiniRacer and gives each program its
+own V8 global state. The core gem does not require or load MiniRacer:
+
+```ruby
+# Gemfile
+gem "mini_racer", "~> 0.21"
+
+# application setup
+require "little_ghost/code_mode/javascript_engine"
+
+LittleGhost.configure do |config|
+  config.code_mode = {engine: :javascript, sandbox: :native}
+end
+```
+
+The JavaScript program has no Node.js APIs, filesystem, network, console,
+WebAssembly, or process-spawning API. Tool methods return Promises, and the
+generated instructions include TypeScript declarations derived from each Tool
+schema. Use `await` or `Promise.all`, `text(value)` for output, and `exit()` to
+complete early. Call `text(value)` first when the value should become
+user-visible output.
+
+MiniRacer's language-level restrictions are useful, but the operating-system
+Sandbox still contains the program. The Ruby parent owns the Tool catalog,
+permission checks, Tool-call limits, events, tracing, and resource cleanup.
+
+## Build a custom engine
+
+Applications can register another `CodeMode::Engine`. An engine names its
+language, writes the instructions shown to the model, and opens a
+`CodeMode::Session`. The session implements `#execute`, `#wait`, `#stop`, and
+`#close`. The first three operations return a `CodeMode::ProgramResult`.
+
+LittleGhost gives the engine a Tool broker and a Sandbox factory. The broker
+stays in the parent Ruby process. The factory creates the Sandbox that
+contains model-written code. An engine may request named runtime paths for its
+interpreter libraries. Those paths are visible to the child process, but they
+never become filesystem grants available through Tools.
+
+The session owns every Workspace, Sandbox, child process, thread, and
+communication channel it creates. It closes those resources in reverse order.
+LittleGhost may use one registered engine instance for concurrent Agent Runs,
+so the engine must keep each program's mutable state inside its session.
+
+A sandboxed engine must use a backend that owns the complete child process tree
+or can prevent child processes. An explicitly unrestricted backend may run an
+engine, but the generated program then has the same host access as the parent.
+
+See `LittleGhost::CodeMode::Engine`, `LittleGhost::CodeMode::Session`, and
+`LittleGhost::CodeMode::ProgramResult` for the extension contract. Continue
+with [Integrations](integrations.md) to connect Runs to MCP tools, AG-UI, and
+OpenTelemetry.