# Class LittleGhost::Invocation

Documentation version: Edge

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

Carry one application request into an agent run. An invocation keeps framework
fields and application-specific context in one indifferent-key environment.

    invocation = LittleGhost::Invocation.new(
      message: "Why is transfer 481 pending?",
      account_id: "account-1",
      metadata: {channel: "customer_support"}
    )

    invocation.message.text  # => "Why is transfer 481 pending?"
    invocation[:account_id]  # => "account-1"
    invocation.account_id    # => "account-1"

String and symbol keys address the same field. Known fields have named
accessors, while unknown application fields remain available through hash
access and dynamic readers or writers. `message` and every `history` entry are
normalized to Message objects; `deadline_at` lazily parses ISO 8601 text.

Missing run, invocation, and session identifiers are generated when the object
is built. Actor identity is never inferred: applications that use it for
persistence or tenant isolation must pass a value established by their trusted
authentication boundary. Invalid payloads, messages, keys, or deadlines raise
InvocationError.

## Inheritance

`LittleGhost::Invocation < Object`

## Class methods

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

```ruby
.new(env = {})
```

Copies `env`, normalizes known framework fields, and fills missing
identifiers.

The payload must be a Hash and must contain a non-blank message.

## Instance methods

<a id="method-i-5B-5D"></a>
### `#[]`

```ruby
#[](key)
```

Looks up `key` after normalizing it to a String.

<a id="method-i-5B-5D-3D"></a>
### `#[]=`

```ruby
#[]=(key, value)
```

Stores `value` under a normalized String key.

The `message` and `history` fields are normalized before storage.

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

```ruby
actor_id() -> value
```

The explicit actor identifier supplied by the application.

<a id="method-i-actor_id-3D"></a>
### `#actor_id=`

```ruby
actor_id=(value) -> value
```

Replaces the application-established actor identifier.

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

```ruby
context() -> Hash
```

JSON-like state made available to the agent run.

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

```ruby
context=(value) -> value
```

Replaces the JSON-like agent state.

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

```ruby
#deadline_at()
```

The request deadline as a Time, parsing ISO 8601 text on first access.

<a id="method-i-deadline_at-3D"></a>
### `#deadline_at=`

```ruby
#deadline_at=(value)
```

Replaces the deadline; parsing is deferred until `deadline_at` is read.

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

```ruby
#dig(key, *names)
```

Traverses the environment from normalized `key` through `names`.

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

```ruby
#fetch(key, *defaults, &block)
```

Fetches `key` with the same default and block behavior as Hash#fetch.

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

```ruby
history() -> Array<LittleGhost::Message>
```

Frozen, normalized Messages that precede the current message.

<a id="method-i-history-3D"></a>
### `#history=`

```ruby
#history=(value)
```

Replaces and freezes the normalized message history.

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

```ruby
invocation_id() -> String
```

The invocation identifier, defaulting to `run_id`.

<a id="method-i-invocation_id-3D"></a>
### `#invocation_id=`

```ruby
invocation_id=(value) -> value
```

Replaces the invocation identifier.

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

```ruby
#key?(key)
```

Whether the environment contains `key` after normalization.

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

```ruby
message() -> LittleGhost::Message
```

The normalized current Message.

<a id="method-i-message-3D"></a>
### `#message=`

```ruby
#message=(value)
```

Replaces and normalizes the current message.

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

```ruby
metadata() -> Hash
```

Application metadata carried with the request.

<a id="method-i-metadata-3D"></a>
### `#metadata=`

```ruby
metadata=(value) -> value
```

Replaces the application metadata.

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

```ruby
run_id() -> String
```

The caller-supplied or generated top-level run identifier.

<a id="method-i-run_id-3D"></a>
### `#run_id=`

```ruby
run_id=(value) -> value
```

Replaces the top-level run identifier.

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

```ruby
session_id() -> String
```

The session identifier, defaulting to `run_id`.

<a id="method-i-session_id-3D"></a>
### `#session_id=`

```ruby
session_id=(value) -> value
```

Replaces the session identifier used for persistence.

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

```ruby
settings() -> Hash
```

Per-request model settings merged after profile defaults. Treat these as
trusted application policy, not unchecked request or model input.

<a id="method-i-settings-3D"></a>
### `#settings=`

```ruby
settings=(value) -> value
```

Replaces the trusted request-scoped model settings.

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

```ruby
#to_h()
```

Produces a mutable copy of the invocation environment.

Nested hashes, arrays, strings, and other duplicable values are copied.