# Class LittleGhost::Run

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Run.html

Observe one top-level assembly execution from start to finish. A run records
its response, outcome, usage, error, and owned resources.

    run = CustomerSupportAgent.ask("Why is transfer 481 pending?")

    run.completed? # => true
    run.outcome    # => "completed"
    run.response   # => "Transfer 481 is waiting for the receiving bank."

`ask` returns the Run after work finishes. `stream_ask` yields StreamEvent
objects as work happens, then returns the same finished Run. A Run executes
only once.

    stream = CustomerSupportAgent.stream_ask("Where is transfer 481?")
    run = stream.each do |event|
      publish(event) if event.type == :text_delta
    end

    run.completed? # => true
    run.response

## Outcomes

Completion, failure, deadline, and cancellation become the `completed`,
`failed`, `partial`, and `cancelled` outcomes. Ordinary execution failures are
available through `error` and the terminal stream event. Failures while
closing resources, delivering events, or reporting instrumentation may still
raise because LittleGhost cannot report a reliable ending.

Tool validation and ToolError failures return safe Tool results to the model,
which may recover and complete the Run. Input, configuration, or resource
construction can raise before a Run exists. Once execution begins, terminal
events are `run_stop`, `run_error`, `run_partial`, and `run_cancel`.

## Owned resources

The Run opens its workspace, sandbox, Session, and Assembly entrypoint, then
closes registered resources in reverse order. `register` adds application
resources to that cleanup sequence. Interjection is available only while one
Agent entrypoint is active.

## Nested Agent events

A composite Assembly stream observes every Agent that shares the Run. Each
`:agent_stream` event carries an AgentStreamSource in
`data[:source]` and a copied, frozen Agent StreamEvent in
`data[:event]`. An inner `:invocation_start` also
includes the copied, frozen Message sent to that Agent in
`data[:input]`. Event consumers cannot change the running work.

Parallel Agents may interleave, but the Run invokes the stream consumer
serially. Contextual events expose data from every participating Agent, so
applications should enable `include_agent_events` only for destinations that
may see every participant's data.

## Inheritance

`LittleGhost::Run < Object`

## Includes

- `Enumerable`

## Attributes

<a id="attribute-i-agent_class"></a>
### `agent_class` (R)

Agent class used for compatibility when the entrypoint is an Agent.

<a id="attribute-i-cancellation_token"></a>
### `cancellation_token` (R)

Token that cooperatively stops this Run and its children.

<a id="attribute-i-entrypoint_class"></a>
### `entrypoint_class` (R)

Public Agent, Workflow, Swarm, or Graph class selected by the caller.

<a id="attribute-i-error"></a>
### `error` (R)

Exception that caused a failed, partial, or cancelled outcome.

<a id="attribute-i-invocation"></a>
### `invocation` (R)

Normalized request carried by this Run.

<a id="attribute-i-operation_id"></a>
### `operation_id` (R)

Unique identifier for this top-level operation.

<a id="attribute-i-outcome"></a>
### `outcome` (R)

Terminal String: `completed`, `failed`, `partial`, or `cancelled`.

<a id="attribute-i-response"></a>
### `response` (R)

Caller-facing final text, or the partial text preserved at a deadline.

<a id="attribute-i-result"></a>
### `result` (R)

Final RunResult, when the Assembly produced one.

<a id="attribute-i-runtime"></a>
### `runtime` (R)

Runtime that built and executes this Run.

<a id="attribute-i-sandbox"></a>
### `sandbox` (R)

Request-scoped sandbox owned or supplied by the Run.

<a id="attribute-i-session"></a>
### `session` (R)

Session opened for this invocation, when persistence is configured.

<a id="attribute-i-usage"></a>
### `usage` (R)

Normalized Usage accumulated by the Run.

<a id="attribute-i-workspace"></a>
### `workspace` (R)

Request-scoped workspace owned or supplied by the Run.

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(invocation:, runtime:, agent_class: nil, assembly_class: nil, entrypoint_class: nil,
      execution_class: nil,
      cancellation_token: Support::CancellationToken.new, workspace: nil, sandbox: nil,
      include_agent_events_by_default: false)
```

Creates a dormant run for `invocation`.

## Instance methods

<a id="method-i-call"></a>
### `#call`

```ruby
#call()
```

Consumes the event stream and returns `self`.

<a id="method-i-cancelled-3F"></a>
### `#cancelled?`

```ruby
#cancelled?()
```

True when cancellation stopped the run without a response.

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

Closes registered resources in reverse order.

The operation is idempotent. It attempts every closer and then raises the
first LittleGhost::CleanupError, or otherwise the first cleanup exception.

<a id="method-i-completed-3F"></a>
### `#completed?`

```ruby
#completed?()
```

True after successful completion.

<a id="method-i-context"></a>
### `#context`

```ruby
#context(state: {}, metadata: {})
```

Creates a RunContext with this run's cancellation token and deadline.

<a id="method-i-each"></a>
### `#each`

```ruby
#each()
```

Yields events and returns `self` after the terminal event.

Without a block, returns an Enumerator. A second execution raises Error.

<a id="method-i-failed-3F"></a>
### `#failed?`

```ruby
#failed?()
```

True after execution or cleanup failed.

<a id="method-i-include_agent_events-3F"></a>
### `#include_agent_events?`

```ruby
#include_agent_events?()
```

Indicates whether the stream includes contextual events from every Agent that
executes as part of this Run.

<a id="method-i-interject"></a>
### `#interject`

```ruby
#interject(message,
      interjection_id: nil,
      batch_key: nil,
      metadata: {},
      cancellation_token: Support::CancellationToken.new,
      deadline: nil)
```

Adds an interjection to the active entrypoint and waits for its response.

Raises LittleGhost::AgentInterjectionError before the entrypoint is ready or
after it finishes.

<a id="method-i-once"></a>
### `#once`

```ruby
#once(key)
```

Performs the block at most once successfully for `key` during this run.

Concurrent callers are serialized. The caller that performs the block receives
its value; later callers receive `nil`. If the block raises, the key is not
recorded and a later call may retry it.

<a id="method-i-partial-3F"></a>
### `#partial?`

```ruby
#partial?()
```

True when the deadline preserved a partial response.

<a id="method-i-register"></a>
### `#register`

```ruby
#register(resource = nil, &closer)
```

Adds a resource or closer to reverse-order cleanup and returns the resource.

A resource must respond to `close` unless a block supplies the cleanup
operation. Registering after the run has closed raises Error.