# `MingaAgent.Session.Continuation`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/session/continuation.ex#L1)

Session-owned lossless model continuation and request identity state.

Display messages live in `MingaAgent.Session.Transcript`; this value contains
only canonical ReqLLM request values. A provider receives an immutable
`Request` and returns an `Outcome`. Only Session applies that outcome.

# `boundary`

```elixir
@type boundary() :: %{
  transcript_id: pos_integer(),
  message_count: non_neg_integer(),
  revision: non_neg_integer()
}
```

Completed model boundary correlated to the last display entry it produced.

# `branch_snapshot`

```elixir
@type branch_snapshot() :: %{messages: [ReqLLM.Message.t()], boundaries: [boundary()]}
```

Lossless model history and boundary identities for one saved display branch.

# `checkpoint_call`

```elixir
@type checkpoint_call() :: %{
  tool_call_id: String.t(),
  name: String.t(),
  arguments: map(),
  status: tool_call_status()
}
```

One ordered tool call in a provider-native assistant response.

# `provenance`

```elixir
@type provenance() :: :lossless | :legacy_reconstructed
```

Origin and continuation guarantee of the stored model history.

# `t`

```elixir
@type t() :: %MingaAgent.Session.Continuation{
  active_request: MingaAgent.Session.Request.t() | nil,
  boundaries: [boundary()],
  branch_messages: %{required(String.t()) => branch_snapshot()},
  durable_revision: non_neg_integer(),
  messages: [ReqLLM.Message.t()],
  provenance: provenance(),
  revision: non_neg_integer(),
  tool_checkpoint: tool_checkpoint() | nil
}
```

Session-owned continuation state.

# `tool_call_status`

```elixir
@type tool_call_status() :: :pending | :admitted | {:completed, ReqLLM.Message.t()}
```

Durable disposition of one provider-issued tool call.

# `tool_checkpoint`

```elixir
@type tool_checkpoint() :: %{
  version: pos_integer(),
  checkpoint_id: String.t(),
  request_id: String.t(),
  messages: [ReqLLM.Message.t()],
  calls: [checkpoint_call()]
}
```

Exact provider continuation captured before any tool effect is admitted.

# `accepts?`

```elixir
@spec accepts?(t(), String.t()) :: boolean()
```

Returns whether an event belongs to the currently admitted request.

# `admit_tool_effect`

```elixir
@spec admit_tool_effect(t(), String.t(), String.t(), String.t(), String.t(), map()) ::
  {:ok, t()} | {:error, term()}
```

Durably grants the only executable token for one checkpointed tool call.

# `begin_request`

```elixir
@spec begin_request(
  t(),
  String.t(),
  pos_integer(),
  String.t() | [ReqLLM.Message.ContentPart.t()]
) ::
  {:ok, MingaAgent.Session.Request.t(), t()}
  | {:error,
     :request_active
     | :effect_reconciliation_required
     | :invalid_attachment
     | :invalid_message}
```

Begins one request by appending the exact user content to the last completed boundary.

# `branch_at`

```elixir
@spec branch_at(t(), String.t(), pos_integer()) ::
  {:ok, t()} | {:error, :branch_not_resumable}
```

Snapshots the original branch and selects the exact boundary for a display entry.

# `cancel`

```elixir
@spec cancel(t()) :: t()
```

Cancels the active request identity without discarding a durable effect checkpoint.

# `checkpoint_tool_group`

```elixir
@spec checkpoint_tool_group(t(), String.t(), [ReqLLM.Message.t()], [map()]) ::
  {:ok, String.t(), t()} | {:error, term()}
```

Captures an exact assistant tool-call group before any call can be admitted.

# `complete`

```elixir
@spec complete(t(), MingaAgent.Session.Outcome.t(), pos_integer()) ::
  {:ok, t()}
  | {:error,
     :stale_outcome
     | :duplicate_outcome
     | :invalid_attachment
     | :invalid_message
     | :unresolved_tool_checkpoint
     | :invalid_checkpoint_progression}
```

Applies an exact matching outcome once and records its display boundary.

# `complete_tool_effect`

```elixir
@spec complete_tool_effect(
  t(),
  String.t(),
  String.t(),
  String.t(),
  ReqLLM.Message.t()
) ::
  {:ok, t()} | {:error, term()}
```

Records the exact terminal tool-result message against its original call identity.

# `durable?`

```elixir
@spec durable?(t()) :: boolean()
```

Returns whether the current completed boundary is durably resumable.

# `import_legacy`

```elixir
@spec import_legacy([MingaAgent.Message.t()]) :: t()
```

Builds an explicitly lossy portable history from an old display-only record.

# `interrupt_request`

```elixir
@spec interrupt_request(t()) :: t()
```

Preserves the exact active request as the basis for a later continuation.

# `mark_durable`

```elixir
@spec mark_durable(t()) :: t()
```

Marks the current completed boundary as durably committed.

# `new`

```elixir
@spec new() :: t()
```

Creates an empty lossless continuation before the first provider request.

# `reconcile_interrupted`

```elixir
@spec reconcile_interrupted(t(), pos_integer()) :: {t(), [map()]}
```

Turns an interrupted checkpoint into a safe exact continuation without replaying calls.

# `reconcile_interrupted`

```elixir
@spec reconcile_interrupted(t(), pos_integer(), %{optional(String.t()) => term()}) ::
  {t(), [map()]}
```

Reconciles with any separately proven durable capture facts keyed by tool call ID.

# `replace_messages`

```elixir
@spec replace_messages(t(), [ReqLLM.Message.t()]) ::
  {:ok, t()}
  | {:error, :request_active | :invalid_attachment | :invalid_message}
```

Installs provider-produced compacted messages as a new Session-owned boundary.

# `replace_system`

```elixir
@spec replace_system(t(), ReqLLM.Message.t()) ::
  {:ok, t()} | {:error, :request_active}
```

Replaces the system prompt through the Session-owned conversation transition.

# `reset`

```elixir
@spec reset(t()) :: t()
```

Starts a fresh logical conversation while preserving no prior request identity.

# `restore`

```elixir
@spec restore(
  [ReqLLM.Message.t()],
  non_neg_integer(),
  non_neg_integer(),
  [boundary()],
  %{required(String.t()) => branch_snapshot()},
  provenance(),
  tool_checkpoint() | nil,
  MingaAgent.Session.Request.t() | nil
) :: {:ok, t()} | {:error, term()}
```

Restores a persisted continuation without changing its recorded provenance.

# `seed_messages`

```elixir
@spec seed_messages(t(), [ReqLLM.Message.t()], pos_integer()) ::
  {:ok, t()}
  | {:error,
     :request_active
     | :effect_reconciliation_required
     | :invalid_attachment
     | :invalid_message}
```

Appends losslessly converted display history and binds it to its final display entry.

# `switch_branch`

```elixir
@spec switch_branch(t(), String.t()) :: {:ok, t()} | {:error, :branch_not_resumable}
```

Restores the lossless model values captured for a named display branch.

# `validate_messages`

```elixir
@spec validate_messages([ReqLLM.Message.t()]) ::
  :ok | {:error, :invalid_message | :invalid_attachment}
```

Validates canonical ReqLLM message fields and required inline attachments.

---

*Consult [api-reference.md](api-reference.md) for complete listing*