Session Continuity

Session continuity is opt-in per run. When enabled, SessionManager rebuilds a provider-agnostic transcript from persisted events and injects it into session.context[:transcript] before adapter execution.

Transcript Model

Continuity uses AgentSessionManager.Core.Transcript:

• session_id
• messages
• last_sequence
• last_timestamp
• metadata

Each transcript message uses canonical fields:

• role (:system | :user | :assistant | :tool)

• content
• tool_call_id
• tool_name
• tool_input
• tool_output
• metadata

Transcript Builder APIs

alias AgentSessionManager.Core.TranscriptBuilder

{:ok, transcript} = TranscriptBuilder.from_events(events, session_id: session.id)
{:ok, transcript} = TranscriptBuilder.from_store(store, session.id, limit: 500)
{:ok, updated} = TranscriptBuilder.update_from_store(store, transcript)

Ordering rules:

1. Prefer sequence_number
2. Fall back to timestamp
3. Use deterministic tie-breakers for stable output

execute_run/4 Continuation Options

{:ok, result} = SessionManager.execute_run(store, adapter, run.id,
  continuation: :auto,
  continuation_opts: [
    limit: 1_000,
    max_messages: 200
  ]
)

Continuation Modes

# Explicit replay mode
{:ok, result} = SessionManager.execute_run(store, adapter, run.id,
  continuation: :replay,
  continuation_opts: [max_messages: 200]
)

# Auto mode
{:ok, result} = SessionManager.execute_run(store, adapter, run.id,
  continuation: :auto
)

Token-Aware Truncation

TranscriptBuilder supports character- and token-based truncation:

{:ok, result} = SessionManager.execute_run(store, adapter, run.id,
  continuation: :auto,
  continuation_opts: [
    max_messages: 200,
    max_chars: 50_000,
    max_tokens_approx: 12_000
  ]
)

• max_chars - hard character budget for transcript content.
• max_tokens_approx - approximate token budget using a 4-chars-per-token heuristic.
• When both are set, the lower effective limit wins.
• Truncation keeps the most recent messages within budget.

Provider Session Metadata

Provider session metadata is stored under session.metadata[:provider_sessions] as a per-provider map:

session.metadata[:provider_sessions]["claude"]
# => %{provider_session_id: "sess_...", model: "claude-haiku-4-5-20251001"}

This supports multi-provider sessions without duplicating top-level metadata keys.

run_once/4 Support

run_once/4 forwards continuity options to execute_run/4:

{:ok, result} = SessionManager.run_once(store, adapter, input,
  continuation: :auto,
  continuation_opts: [max_messages: 100]
)

Adapter Options Pass-Through

{:ok, result} = SessionManager.execute_run(store, adapter, run.id,
  continuation: :auto,
  continuation_opts: [max_messages: 100, max_chars: 50_000],
  adapter_opts: [timeout: 120_000]
)

adapter_opts is forwarded to ProviderAdapter.execute/4 while SessionManager handles orchestration.