MingaClaudeBridge.History (minga_claude_bridge v0.1.0)

Copy Markdown View Source

Decides whether a Minga request continues the live Claude Code session or must start a fresh one.

A Claude Code session has already seen part of the conversation. A follow-up request can continue it only when the request's history starts with exactly what the session saw and adds only input Claude Code has not seen yet: tool results or new user messages. Anything else (an edit, a branch, a reset, a compaction, a changed system prompt, tool set, or model) needs a fresh session that imports the request's history.

Inputs

The route layer normalizes a Minga request into a request/0:

  • purpose - :turn for a normal agent turn. :summary and :title requests are side queries; compare/2 returns :isolated for them and they never touch the session.
  • entries - the conversation as a list of entry/0, oldest first, without the system prompt. Each entry is %{role: :user | :assistant | :tool, digest_input: term()}. digest_input is any term that holds everything about the message that Claude Code would see: text, images, tool calls with ids and arguments, tool results with ids, content and error flag. Metadata that Claude Code does not see (timestamps, usage, local ids) must be left out, or equal messages will not compare equal. The same message must produce the same digest_input every time, including the assistant messages the bridge itself built from a streamed reply.

  • fingerprint - %{system_prompt: term(), tools: term(), model: String.t()}. tools holds the tool declarations with their schemas.

State

t/0 holds only SHA-256 digests: one per entry the session has seen, in order, and one for the fingerprint. Each digest is :crypto.hash(:sha256, :erlang.term_to_binary(term, [:deterministic])). No message content is stored.

Rules

compare/2 checks, in this order:

  1. purpose is not :turn: :isolated.
  2. The session has seen no entries: {:fresh, :empty_session}.
  3. The fingerprint digest differs: {:fresh, :fingerprint_changed}.
  4. The request has fewer entries than the session saw, or any seen position has a different digest: {:fresh, :diverged}.
  5. The request adds no entries: {:fresh, :no_new_entries}. Claude Code cannot produce another reply to input it already answered, so a regenerate starts fresh.
  6. An added entry has role :assistant: {:fresh, :assistant_appended}. The session did not produce that reply, so Claude Code's transcript would not contain it.
  7. Otherwise: {:continue, new_entries}, where new_entries are the added user and tool entries, in order.

record/2 installs the conversation a completed turn leaves behind: the request's entries followed by the assistant entries the session produced, and the request's fingerprint. Record after every completed turn, including a turn that stopped for tool calls, and after a fresh session imports history. Do not record isolated requests.

Summary

Types

A SHA-256 digest.

One normalized conversation message. See the module documentation for what digest_input must hold.

t()

Functions

Compares a request against what the session has seen. See the module documentation for the rules.

Returns the state of a session that has seen nothing.

Returns the state after a completed turn left conversation behind.

Returns the number of entries the session has seen.

Types

comparison()

@type comparison() :: {:continue, [entry()]} | {:fresh, fresh_reason()} | :isolated

digest()

@type digest() :: <<_::256>>

A SHA-256 digest.

entry()

@type entry() :: %{role: role(), digest_input: term()}

One normalized conversation message. See the module documentation for what digest_input must hold.

fingerprint()

@type fingerprint() :: %{system_prompt: term(), tools: term(), model: String.t()}

fresh_reason()

@type fresh_reason() ::
  :empty_session
  | :fingerprint_changed
  | :diverged
  | :no_new_entries
  | :assistant_appended

purpose()

@type purpose() :: :turn | :summary | :title

request()

@type request() :: %{
  purpose: purpose(),
  entries: [entry()],
  fingerprint: fingerprint()
}

role()

@type role() :: :user | :assistant | :tool

t()

@opaque t()

Functions

compare(seen, map)

@spec compare(t(), request()) :: comparison()

Compares a request against what the session has seen. See the module documentation for the rules.

new()

@spec new() :: t()

Returns the state of a session that has seen nothing.

record(history, map)

@spec record(t(), %{entries: [entry()], fingerprint: fingerprint()}) :: t()

Returns the state after a completed turn left conversation behind.

seen_count(history)

@spec seen_count(t()) :: non_neg_integer()

Returns the number of entries the session has seen.