# Class LittleGhost::RunContext

Documentation version: Edge

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

RunContext gives tools and workflows one place for shared state, cancellation,
deadlines, checkpoints, and accumulated usage. It travels with work inside a
run without becoming global process state.

Tools and workflows use it to share JSON-like state, check cancellation and
deadlines, checkpoint messages, and accumulate usage. Framework-managed fields
remain safe when calls overlap on threads or fibers.

## Inheritance

`LittleGhost::RunContext < Object`

## Attributes

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

Active Agent operation identifier, after the context is bound.

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

Token used to cooperatively stop the current work.

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

Durable subagent conversation identifier, when present.

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

Wall-clock deadline for the current work, when present.

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

Framework metadata attached to this context.

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

Mutable DataMap state supplied to this invocation. A top-level Run starts with
restored Session state merged with current Invocation context; child
Assemblies may receive copied, mapped, or empty state. Application code must
synchronize mutations when parallel Tools share this map, or use exclusive
Tools. String and Symbol keys address the same value; persisted snapshots use
canonical String keys.

## Class methods

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

```ruby
.new(state: {},
      cancellation_token: Support::CancellationToken.new,
      deadline: nil,
      metadata: {},
      checkpoint: nil,
      conversation_id: nil,
      interjection_metadata: nil,
      interjection_ids: [])
```

Creates a context with optional checkpoint and interjection state.

## Instance methods

<a id="method-i-check-21"></a>
### `#check!`

```ruby
#check!()
```

Raises LittleGhost::CancelledError or LittleGhost::DeadlineExceededError when
execution should stop.

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

```ruby
#checkpoint(messages)
```

Sends `messages` and current state to the configured checkpoint callback. With
no checkpoint callback, this method does nothing and returns `nil`.

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

```ruby
#record_usage(value)
```

Adds `value` to accumulated model usage.

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

```ruby
#remaining_time(maximum = nil)
```

Calculates seconds remaining before the deadline.

When `maximum` is provided, the result is capped at that value. With no
deadline, returns `maximum`.

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

```ruby
#structured_result()
```

Finds the latest validated structured result, if any.

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

```ruby
#submit_structured_result(result)
```

Stores a validated LittleGhost::StructuredResult and returns it.

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

```ruby
#usage()
```

Takes a snapshot of accumulated usage.