MingaAgent.Session.Continuation (Minga v0.1.0)

Copy Markdown View Source

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.

Summary

Types

boundary()

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

branch_snapshot()

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

checkpoint_call()

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

provenance()

Origin and continuation guarantee of the stored model history.

t()

Session-owned continuation state.

tool_call_status()

Durable disposition of one provider-issued tool call.

tool_checkpoint()

Exact provider continuation captured before any tool effect is admitted.

Functions

accepts?(continuation, request_id)

Returns whether an event belongs to the currently admitted request.

admit_tool_effect(continuation, request_id, checkpoint_id, tool_call_id, name, arguments)

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

begin_request(continuation, request_id, turn_id, content)

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

branch_at(continuation, branch_name, transcript_id)

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

cancel(continuation)

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

checkpoint_tool_group(continuation, request_id, messages, calls)

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

complete(continuation, outcome, transcript_id)

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

complete_tool_effect(continuation, request_id, checkpoint_id, tool_call_id, result_message)

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

durable?(continuation)

Returns whether the current completed boundary is durably resumable.

import_legacy(display_messages)

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

interrupt_request(continuation)

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

mark_durable(continuation)

Marks the current completed boundary as durably committed.

new()

Creates an empty lossless continuation before the first provider request.

reconcile_interrupted(continuation, transcript_id)

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

reconcile_interrupted(continuation, transcript_id, outputs)

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

replace_messages(continuation, messages)

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

replace_system(continuation, system_message)

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

reset(continuation)

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

restore(messages, revision, durable_revision, boundaries, branch_messages, provenance, tool_checkpoint \\ nil, active_request \\ nil)

Restores a persisted continuation without changing its recorded provenance.

seed_messages(continuation, messages, transcript_id)

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

switch_branch(continuation, branch_name)

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

validate_messages(messages)

Validates canonical ReqLLM message fields and required inline attachments.

Types

boundary()

@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()

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

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

checkpoint_call()

@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()

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

Origin and continuation guarantee of the stored model history.

t()

@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()

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

Durable disposition of one provider-issued tool call.

tool_checkpoint()

@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.

Functions

accepts?(continuation, request_id)

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

Returns whether an event belongs to the currently admitted request.

admit_tool_effect(continuation, request_id, checkpoint_id, tool_call_id, name, arguments)

@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(continuation, request_id, turn_id, content)

@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(continuation, branch_name, transcript_id)

@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(continuation)

@spec cancel(t()) :: t()

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

checkpoint_tool_group(continuation, request_id, messages, calls)

@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(continuation, outcome, transcript_id)

@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(continuation, request_id, checkpoint_id, tool_call_id, result_message)

@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?(continuation)

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

Returns whether the current completed boundary is durably resumable.

import_legacy(display_messages)

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

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

interrupt_request(continuation)

@spec interrupt_request(t()) :: t()

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

mark_durable(continuation)

@spec mark_durable(t()) :: t()

Marks the current completed boundary as durably committed.

new()

@spec new() :: t()

Creates an empty lossless continuation before the first provider request.

reconcile_interrupted(continuation, transcript_id)

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

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

reconcile_interrupted(continuation, transcript_id, outputs)

@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(continuation, messages)

@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(continuation, system_message)

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

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

reset(continuation)

@spec reset(t()) :: t()

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

restore(messages, revision, durable_revision, boundaries, branch_messages, provenance, tool_checkpoint \\ nil, active_request \\ nil)

@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(continuation, messages, transcript_id)

@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(continuation, branch_name)

@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(messages)

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

Validates canonical ReqLLM message fields and required inline attachments.